@rohitaryal/whisk-api 1.0.4 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +209 -119
  2. package/package.json +47 -45
package/README.md CHANGED
@@ -1,153 +1,243 @@
1
- # whisk-api
2
-
3
- [![Test](https://github.com/rohitaryal/whisk-api/actions/workflows/test.yaml/badge.svg)](https://github.com/rohitaryal/whisk-api/actions/workflows/test.yaml)
4
- [![License](https://img.shields.io/npm/l/whisk-api.svg)](https://github.com/rohitaryal/whisk-api/blob/main/LICENSE)
5
- [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
6
- [![Node.js](https://img.shields.io/badge/Node.js-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
7
- [![Bun.js](https://img.shields.io/badge/Bun.js-000000?logo=bun&logoColor=pink)](https://nodejs.org/)
8
1
 
9
- An unofficial TypeScript/JavaScript API wrapper for Google Labs' Whisk image generation platform.
2
+ # whisk-api
10
3
 
11
- ## Features
4
+ Unofficial free reverse engineered API for Google's Whisk from [labs.google](https://labs.google).
12
5
 
13
- - **Image Generation**: Create high-quality images from text prompts
14
- - **Image Refinement**: Enhance and modify existing generated images
15
- - **Project Management**: Organize generations into projects with full CRUD operations
16
- - **Media Management**: Access generation history and download images
17
- - **Multiple Models**: Support for various Imagen models with different capabilities
18
- - **Type Safety**: Full TypeScript support with comprehensive type definitions
6
+ ![Banner](https://raw.githubusercontent.com/rohitaryal/whisk-api/refs/heads/main/assets/banner.jpeg)
19
7
 
20
8
  ## Installation
21
9
 
22
10
  ```bash
23
- bun i @rohitaryal/whisk-api
11
+ npm i -g @rohitaryal/whisk-api
24
12
  # or
25
- npm i @rohitaryal/whisk-api
13
+ bun i -g @rohitaryal/whisk-api
26
14
  ```
27
15
 
28
- ## Quick Start
16
+ ## Features
29
17
 
30
- ```typescript
31
- import Whisk from '@rohitaryal/whisk-api';
18
+ 1. Text to Image using `IMAGEN_3_5`
19
+ 2. Image to Video (Animation) using `VEO`
20
+ 3. Image Refinement (Editing/Inpainting using NanoBanana)
21
+ 4. Image to Text
22
+ 5. Project & Media Management
23
+ 6. Command line support
32
24
 
33
- const whisk = new Whisk({
34
- cookie: "your_google_labs_cookie_here"
35
- });
25
+ ## Usage
36
26
 
37
- // Generate an image
38
- const result = await whisk.generateImage({
39
- prompt: "A serene mountain landscape at sunset"
40
- });
27
+ `whisk` can be invoked through both command line and as a module.
41
28
 
42
- if (result.Ok) {
43
- const imageData = result.Ok.imagePanels[0]?.generatedImages[0]?.encodedImage;
44
- whisk.saveImage(imageData, "mountain_sunset.png");
45
- }
46
- ```
29
+ <details>
30
+ <summary style="font-weight: bold;font-size:15px;">Command Line</summary>
47
31
 
48
- ## Authentication
49
-
50
- You'll need to obtain your Google Labs session cookie:
51
-
52
- 1. Visit [labs.google/fx/tools/whisk](https://labs.google/fx/tools/whisk)
53
- 2. Open browser developer tools (F12)
54
- 3. Go to Application/Storage → Cookies
55
- 4. Copy the cookie value and use it in your configuration
56
-
57
- ## Supported Models
58
-
59
- | Model | Description | Capabilities |
60
- |-------|-------------|--------------|
61
- | **Imagen 2** | Second generation model | Standard quality image generation |
62
- | **Imagen 3** | Third generation model | Improved quality and prompt adherence |
63
- | **Imagen 3.1** | Enhanced version of Imagen 3 | Better detail rendering |
64
- | **Imagen 4** | Latest generation model | Highest quality, best prompt understanding |
65
- | **Imagen 3 Portrait** | Portrait-optimized variant | Specialized for portrait generation |
66
- | **Imagen 3 Landscape** | Landscape-optimized variant | Specialized for landscape generation |
67
- | **Imagen 3 Portrait 3:4** | Portrait with 3:4 aspect ratio | Fixed aspect ratio portraits |
68
- | **Imagen 3 Landscape 4:3** | Landscape with 4:3 aspect ratio | Fixed aspect ratio landscapes |
69
-
70
- ## Examples
71
-
72
- The library includes comprehensive examples in the [`examples/`](examples/) directory:
73
-
74
- - [Getting authorization tokens](examples/1_get_auth_tokens.ts)
75
- - [Checking credit status](examples/2_get_credit_status.ts)
76
- - [Creating projects](examples/3_create_new_project.ts)
77
- - [Managing project history](examples/4_list_all_project_history.ts)
78
- - [Project content management](examples/5_get_content_of_projects.ts)
79
- - [Deleting projects](examples/6_delete_projects.ts)
80
- - [Renaming projects](examples/7_rename_project.ts)
81
- - [Image generation history](examples/8_get_image_generation_history.ts)
82
- - [Saving images](examples/9_save_images.ts)
83
- - [Basic image generation](examples/10_generate_image.ts)
84
- - [Image refinement](examples/11_refine_image.ts)
85
-
86
- ## API Reference
87
-
88
- ### Core Methods
89
-
90
- - `generateImage(prompt)` - Generate images from text prompts
91
- - `refineImage(refinementRequest)` - Refine existing images with new prompts
92
- - `getProjectHistory(limit)` - Retrieve project history
93
- - `getImageHistory(limit)` - Retrieve image generation history
94
- - `getNewProjectId(title)` - Create new projects
95
- - `deleteProjects(projectIds)` - Delete multiple projects
96
- - `renameProject(newName, projectId)` - Rename existing projects
97
- - `saveImage(base64Data, fileName)` - Save images to disk
98
- - `getAuthorizationToken()` - Generate authentication tokens
99
-
100
- ### Response Format
101
-
102
- All methods return a `Result<T>` type with either:
103
- - `Ok`: Contains the successful response data
104
- - `Err`: Contains error information
105
-
106
- ```typescript
107
- const result = await whisk.generateImage({ prompt: "example" });
108
- if (result.Err) {
109
- console.error("Generation failed:", result.Err);
110
- } else {
111
- console.log("Success:", result.Ok);
112
- }
113
- ```
32
+ Make sure you have:
114
33
 
115
- ## Development
34
+ 1. Installed `whisk-api` globally ([How to install?](#installation))
35
+ 2. Obtained your google account cookies ([How to get cookies?](#help))
36
+ 3. Set env variable `COOKIE` containing your cookie
116
37
 
117
- ```bash
118
- # Install dependencies
119
- bun install
38
+ Bash:
39
+
40
+ ```bash
41
+ export COOKIE="__YOUR__COOKIE__HERE__"
42
+ ```
43
+
44
+ Command Prompt:
45
+
46
+ ```bat
47
+ set "COOKIE=__YOUR__COOKIE__HERE__"
48
+ ```
49
+
50
+ Powershell:
51
+
52
+ ```ps
53
+ $COOKIE = "__YOUR__GOOGLE__COOKIE__HERE__"
54
+ ```
55
+
56
+ #### Basic Usages
57
+
58
+ > **NOTE:**
59
+ > If you are using environment variables, keep the quotes around cookie to avoid word-splitting and authentication errors.
60
+ >
61
+ > - Linux/macOS: `"$COOKIE"`
62
+ > - PowerShell: `"$env:COOKIE"`
63
+ > - Command Prompt: `"%COOKIE%"`
120
64
 
121
- # Set up environment
122
- export COOKIE="your_cookie_here"
65
+ - Generating image with prompt
123
66
 
124
- # Run tests
125
- bun test
67
+ ```bash
68
+ # saves generated image at ./output/ by default
69
+ whisk generate --prompt "A bad friend" --cookie "$COOKIE"
70
+ ```
126
71
 
72
+ - Selecting a specific aspect ratio
73
+
74
+ ```bash
75
+ # Available: SQUARE, PORTRAIT, LANDSCAPE (Default: LANDSCAPE)
76
+ whisk generate --prompt "Reptillian CEO" --aspect "PORTRAIT" --cookie "$COOKIE"
77
+ ```
78
+
79
+ - Animating an existing image (Image to Video)
80
+
81
+ ```bash
82
+ # Requires the Media ID of a LANDSCAPE image
83
+ whisk animate "__MEDIA__ID__HERE__" --script "Camera pans slowly to the left" --cookie "$COOKIE"
84
+ ```
85
+
86
+ - Refining (Editing) an image
87
+
88
+ ```bash
89
+ whisk refine "__MEDIA__ID__HERE__" --prompt "Add a red hat to the character" --cookie "$COOKIE"
90
+ ```
91
+
92
+ - Generating caption from a local image file
93
+
94
+ ```bash
95
+ whisk caption --file /path/to/img.webp --count 3 --cookie "$COOKIE"
96
+ ```
97
+
98
+ - Deleting media from the cloud
99
+
100
+ ```bash
101
+ whisk delete "__MEDIA__ID__HERE__" --cookie "$COOKIE"
102
+ ```
103
+
104
+ Full generation help:
105
+
106
+ ```text
107
+ whisk generate <options>
108
+
109
+ Options:
110
+ --version Show version number
111
+ -h, --help Show help
112
+ -p, --prompt Description of the image
113
+ -m, --model Image generation model (Default: IMAGEN_3_5)
114
+ -a, --aspect Aspect ratio (SQUARE, PORTRAIT, LANDSCAPE)
115
+ -s, --seed Seed value (0 for random)
116
+ -d, --dir Output directory
117
+ -c, --cookie Google account cookie
127
118
  ```
128
119
 
129
- ## Testing
120
+ Full animation help:
130
121
 
131
- The test suite requires a valid Google Labs cookie. Set the `COOKIE` environment variable and run:
122
+ ```text
123
+ whisk animate <mediaId>
132
124
 
133
- ```bash
134
- bun test
125
+ Positionals:
126
+ mediaId The ID of the image to animate
127
+
128
+ Options:
129
+ -s, --script Prompt/Script for the video animation
130
+ -m, --model Video generation model (Default: VEO_FAST_3_1)
131
+ -d, --dir Output directory
132
+ -c, --cookie Google account cookie
135
133
  ```
136
134
 
137
- ## Limitations
135
+ Full fetch help:
136
+
137
+ ```text
138
+ whisk fetch <mediaId>
139
+
140
+ Positionals:
141
+ mediaId Unique ID of generated media
142
+
143
+ Options:
144
+ -d, --dir Output directory
145
+ -c, --cookie Google account cookie
146
+ ```
147
+
148
+ </details>
149
+
150
+ <details>
151
+ <summary style="font-weight: bold;font-size:15px;">Importing as module</summary>
152
+
153
+ - Basic image generation
154
+
155
+ ```typescript
156
+ import { Whisk } from "@rohitaryal/whisk-api";
157
+
158
+ const whisk = new Whisk(process.env.COOKIE);
159
+
160
+ // 1. Create a project context
161
+ const project = await whisk.newProject("My Project");
162
+
163
+ // 2. Generate image
164
+ const media = await project.generateImage("A big black cockroach");
165
+
166
+ // 3. Save to disk
167
+ const savedPath = media.save("./output");
168
+ console.log("[+] Image saved at: " + savedPath);
169
+ ```
170
+
171
+ - Advanced Workflow (Gen -> Refine -> Animate)
172
+
173
+ ```typescript
174
+ import { Whisk, ImageAspectRatio } from "@rohitaryal/whisk-api";
175
+
176
+ const whisk = new Whisk(process.env.COOKIE);
177
+ const project = await whisk.newProject("Video Workflow");
178
+
179
+ // 1. Generate Base Image (Must be LANDSCAPE for video)
180
+ const baseImage = await project.generateImage({
181
+ prompt: "A cybernetic city",
182
+ aspectRatio: "IMAGE_ASPECT_RATIO_LANDSCAPE"
183
+ });
184
+
185
+ // 2. Refine (Edit)
186
+ const refinedImage = await baseImage.refine("Make it raining neon rain");
187
+
188
+ // 3. Animate (Video)
189
+ const video = await refinedImage.animate("Camera flies through the streets", "VEO_FAST_3_1");
190
+
191
+ video.save("./videos");
192
+ ```
193
+
194
+ More examples are at: [/examples](https://github.com/rohitaryal/imageFX-api/tree/main/examples)
195
+ </details>
196
+
197
+ ## Help
198
+
199
+ <details>
200
+ <summary style="font-weight: bold;font-size:15px;">How to extract cookies?</summary>
201
+
202
+ #### Easy way
203
+
204
+ 1. Install [Cookie Editor](https://github.com/Moustachauve/cookie-editor) extension in your browser.
205
+ 2. Open [labs.google](https://labs.google/fx/tools/whisk/project), make sure you are logged in
206
+ 3. Click on <kbd>Cookie Editor</kbd> icon from Extensions section.
207
+ 4. Click on <kbd>Export</kbd> -> <kbd>Header String</kbd>
208
+
209
+ #### Manual way
210
+
211
+ 1. Open [labs.google](https://labs.google/fx/tools/whisk/project), make sure you are logged in
212
+ 2. Press <kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>I</kbd> to open console
213
+ 3. Click on <kbd>Network</kbd> tab at top of console
214
+ 4. Press <kbd>CTRL</kbd> + <kbd>L</kbd> to clear network logs
215
+ 5. Click <kbd>CTRL</kbd> + <kbd>R</kbd> to refresh page
216
+ 6. Click on `image-fx` which should be at top
217
+ 7. Goto <kbd>Request Headers</kbd> section and copy all the content of <kbd>Cookie</kbd>
218
+
219
+ </details>
220
+
221
+ <details>
222
+ <summary style="font-weight: bold;font-size:15px;">ImageFX not available in your country?</summary>
223
+
224
+ 1. Install a free VPN (Windscribe, Proton, etc)
225
+ 2. Open [labs.google](https://labs.google/fx/tools/whisk/project) and login
226
+ 3. From here follow the "How to extract cookie?" in [HELP](#help) section (above).
227
+ 4. Once you have obtained this cookie, you don't need VPN anymore.
138
228
 
139
- - Requires valid Google's logged in cookies.
140
- - Regional availability may vary
141
- - Unofficial API subject to changes
229
+ </details>
142
230
 
143
- ## Contributing
231
+ <details>
232
+ <summary style="font-weight: bold;font-size:15px;">Not able to generate images?</summary>
144
233
 
145
- Contributions are welcome. Please ensure all tests pass and follow the existing code style.
234
+ Create an issue [here](https://github.com/rohitaryal/imageFX-api/issues). Make sure the pasted logs don't contain cookie or tokens.
235
+ </details>
146
236
 
147
- ## License
237
+ ## Contributions
148
238
 
149
- This project is for educational and research purposes. Please respect Google's terms of service when using this library.
239
+ Contribution are welcome but ensure to pass all test cases and follow existing coding standard.
150
240
 
151
241
  ## Disclaimer
152
242
 
153
- This is an unofficial API wrapper and is not affiliated with Google. Use at your own risk and ensure compliance with Google's terms of service.
243
+ This project demonstrates usage of Google's private API but is not affiliated with Google. Use at your own risk.
package/package.json CHANGED
@@ -1,47 +1,49 @@
1
1
  {
2
- "name": "@rohitaryal/whisk-api",
3
- "version": "1.0.4",
4
- "type": "module",
5
- "main": "./dist/index.js",
6
- "types": "./dist/index.d.ts",
7
- "files": [
8
- "dist"
9
- ],
10
- "private": false,
11
- "scripts": {
12
- "test": "bun test",
13
- "build": "tsc && chmod +x ./dist/index.js"
14
- },
15
- "devDependencies": {
16
- "@types/bun": "latest",
17
- "typescript": "^5.8.3"
18
- },
19
- "peerDependencies": {
20
- "typescript": "^5"
21
- },
22
- "dependencies": {
23
- "bun-types": "^1.2.14",
24
- "undici-types": "^6.21.0"
25
- },
26
- "repository": {
27
- "type": "git",
28
- "url": "git+https://github.com/rohitaryal/whisk-api.git"
29
- },
30
- "keywords": [
31
- "whisk",
32
- "whisk-api",
33
- "ai-image-generator",
34
- "labs-google"
35
- ],
36
- "author": "rohitaryal",
37
- "license": "MIT",
38
- "bugs": {
39
- "url": "https://github.com/rohitaryal/whisk-api/issues"
40
- },
41
- "homepage": "https://github.com/rohitaryal/whisk-api#readme",
42
- "directories": {
43
- "example": "examples",
44
- "test": "tests"
45
- },
46
- "description": "Unofficial API for Whisk image generation."
2
+ "name": "@rohitaryal/whisk-api",
3
+ "version": "2.0.0",
4
+ "type": "module",
5
+ "main": "./dist/index.js",
6
+ "types": "./dist/index.d.ts",
7
+ "files": [
8
+ "dist"
9
+ ],
10
+ "private": false,
11
+ "scripts": {
12
+ "test": "bun test",
13
+ "build": "tsc && chmod +x ./dist/index.js"
14
+ },
15
+ "devDependencies": {
16
+ "@types/bun": "^1.3.5",
17
+ "@types/yargs": "^17.0.35",
18
+ "typescript": "^5.8.3"
19
+ },
20
+ "peerDependencies": {
21
+ "typescript": "^5"
22
+ },
23
+ "dependencies": {
24
+ "bun-types": "^1.2.14",
25
+ "undici-types": "^6.21.0",
26
+ "yargs": "^18.0.0"
27
+ },
28
+ "repository": {
29
+ "type": "git",
30
+ "url": "git+https://github.com/rohitaryal/whisk-api.git"
31
+ },
32
+ "keywords": [
33
+ "whisk",
34
+ "whisk-api",
35
+ "ai-image-generator",
36
+ "labs-google"
37
+ ],
38
+ "author": "rohitaryal",
39
+ "license": "MIT",
40
+ "bugs": {
41
+ "url": "https://github.com/rohitaryal/whisk-api/issues"
42
+ },
43
+ "homepage": "https://github.com/rohitaryal/whisk-api#readme",
44
+ "directories": {
45
+ "example": "examples",
46
+ "test": "tests"
47
+ },
48
+ "description": "Unofficial API for Whisk image generation."
47
49
  }