# whisk-api
Unofficial free reverse engineered API for Google's Whisk from [labs.google](https://labs.google).
## Installation
```bash
npm i -g @rohitaryal/whisk-api
# or
bun i -g @rohitaryal/whisk-api
```
## Features
1. Text to Image using `IMAGEN_3_5`
2. Image to Video (Animation) using `VEO_3_1`
3. Image Refinement (Editing/Inpainting)
4. Image to Text (Caption Generation)
5. Project & Media Management
6. Upload & Reference Images
7. Command line support
## Usage
`whisk` can be invoked through both command line and as a module.
Command Line
Make sure you have:
1. Installed `whisk-api` globally ([How to install?](#installation))
2. Obtained your google account cookies ([How to get cookies?](#help))
3. Set env variable `COOKIE` containing your cookie
Bash:
```bash
export COOKIE="__YOUR__COOKIE__HERE__"
```
Command Prompt:
```bat
set "COOKIE=__YOUR__COOKIE__HERE__"
```
Powershell:
```ps
$COOKIE = "__YOUR__GOOGLE__COOKIE__HERE__"
```
#### Basic Usages
> **NOTE:**
> If you are using environment variables, keep the quotes around cookie to avoid word-splitting and authentication errors.
>
> - Linux/macOS: `"$COOKIE"`
> - PowerShell: `"$env:COOKIE"`
> - Command Prompt: `"%COOKIE%"`
- Creating a new project
```bash
whisk project --name "My Project" --cookie "$COOKIE"
```
- Generating image with prompt
```bash
# saves generated image at ./output/ by default
whisk generate --prompt "A bad friend" --cookie "$COOKIE"
```
- Selecting a specific aspect ratio
```bash
# Available: SQUARE, PORTRAIT, LANDSCAPE (Default: LANDSCAPE)
whisk generate --prompt "Reptillian CEO" --aspect "PORTRAIT" --cookie "$COOKIE"
```
- Animating an existing image (Image to Video)
```bash
# Requires the Media ID of a LANDSCAPE image
whisk animate "__MEDIA__ID__HERE__" --script "Camera pans slowly to the left" --cookie "$COOKIE"
```
- Refining (Editing) an image
```bash
whisk refine "__MEDIA__ID__HERE__" --prompt "Add a red hat to the character" --cookie "$COOKIE"
```
- Generating caption from a local image file
```bash
whisk caption --file /path/to/img.webp --count 3 --cookie "$COOKIE"
```
- Fetching an existing media by ID
```bash
whisk fetch "__MEDIA__ID__HERE__" --cookie "$COOKIE"
```
- Uploading an image as reference
```bash
whisk upload /path/to/image.jpg --category SUBJECT --project "__PROJECT__ID__" --cookie "$COOKIE"
```
- Deleting media from the cloud
```bash
whisk delete "__MEDIA__ID__HERE__" --cookie "$COOKIE"
```
Full CLI commands help:
```text
whisk [args]
Commands:
whisk project Generate a new project
whisk generate Generate new images using a temporary project
whisk animate Animate an existing landscape image into a video
whisk refine Edit/Refine an existing image
whisk caption Generate captions for a local image file
whisk fetch Download an existing generated media by ID
whisk upload Upload an image to be used as reference later
whisk delete Delete a generated media from the cloud
Options:
-c, --cookie Google account cookie [required]
-h, --help Show help
--version Show version number
```
Project Command
```text
whisk project
Options:
--name Project name [default: "Whisk-CLI project"]
-c, --cookie Google account cookie [required]
```
Generate Command
```text
whisk generate
Options:
-p, --prompt Description of the image [required]
-m, --model Image generation model [default: "IMAGEN_3_5"]
-a, --aspect Aspect ratio (SQUARE, PORTRAIT, LANDSCAPE) [default: "LANDSCAPE"]
-s, --seed Seed value (0 for random) [default: 0]
-d, --dir Output directory [default: "./output"]
-c, --cookie Google account cookie [required]
```
Animate Command
```text
whisk animate
Positionals:
mediaId The ID of the image to animate [required]
Options:
-s, --script Prompt/Script for the video animation [required]
-m, --model Video generation model [default: "VEO_3_1"]
-d, --dir Output directory [default: "./output"]
-c, --cookie Google account cookie [required]
```
Refine Command
```text
whisk refine
Positionals:
mediaId The ID of the image to refine [required]
Options:
-p, --prompt Instruction for editing (e.g., 'Make it snowy') [required]
-d, --dir Output directory [default: "./output"]
-c, --cookie Google account cookie [required]
```
Caption Command
```text
whisk caption
Options:
-f, --file Path to local image file [required]
-n, --count Number of captions [default: 1]
-c, --cookie Google account cookie [required]
```
Fetch Command
```text
whisk fetch
Positionals:
mediaId Unique ID of generated media [required]
Options:
-d, --dir Output directory [default: "./output"]
-c, --cookie Google account cookie [required]
```
Upload Command
```text
whisk upload
Positionals:
file Path to local image file [required]
Options:
--category, -ca Category of reference [required]
Choices: SUBJECT, SCENE, STYLE
--project, -pr Project/Workflow ID [required]
-c, --cookie Google account cookie [required]
```
Delete Command
```text
whisk delete
Positionals:
mediaId Unique ID of generated media to delete [required]
Options:
-c, --cookie Google account cookie [required]
```
Importing as module
- Basic image generation
```typescript
import { Whisk } from "@rohitaryal/whisk-api";
const whisk = new Whisk(process.env.COOKIE);
// 1. Create a project context
const project = await whisk.newProject("My Project");
// 2. Generate image
const media = await project.generateImage("A big black cockroach");
// 3. Save to disk
const savedPath = media.save("./output");
console.log("[+] Image saved at: " + savedPath);
```
- Advanced Workflow (Gen -> Refine -> Animate)
```typescript
import { Whisk, ImageAspectRatio } from "@rohitaryal/whisk-api";
const whisk = new Whisk(process.env.COOKIE);
const project = await whisk.newProject("Video Workflow");
// 1. Generate Base Image (Must be LANDSCAPE for video)
const baseImage = await project.generateImage({
prompt: "A cybernetic city",
aspectRatio: "IMAGE_ASPECT_RATIO_LANDSCAPE"
});
// 2. Refine (Edit)
const refinedImage = await baseImage.refine("Make it raining neon rain");
// 3. Animate (Video)
const video = await refinedImage.animate("Camera flies through the streets", "VEO_3_1_I2V_12STEP");
video.save("./videos");
```
More examples are at: [/examples](https://github.com/rohitaryal/whisk-api/tree/main/examples)
## Help
How to extract cookies?
#### Easy way
1. Install [Cookie Editor](https://github.com/Moustachauve/cookie-editor) extension in your browser.
2. Open [labs.google](https://labs.google/fx/tools/whisk/project), make sure you are logged in
3. Click on Cookie Editor icon from Extensions section.
4. Click on Export -> Header String
#### Manual way
1. Open [labs.google](https://labs.google/fx/tools/whisk/project), make sure you are logged in
2. Press CTRL + SHIFT + I to open console
3. Click on Network tab at top of console
4. Press CTRL + L to clear network logs
5. Click CTRL + R to refresh page
6. Click on `image-fx` which should be at top
7. Goto Request Headers section and copy all the content of Cookie
ImageFX not available in your country?
1. Install a free VPN (Windscribe, Proton, etc)
2. Open [labs.google](https://labs.google/fx/tools/whisk/project) and login
3. From here follow the "How to extract cookie?" in [HELP](#help) section (above).
4. Once you have obtained this cookie, you don't need VPN anymore.
Not able to generate images?
Create an issue [here](https://github.com/rohitaryal/imageFX-api/issues). Make sure the pasted logs don't contain cookie or tokens.
## Contributions
Contribution are welcome but ensure to pass all test cases and follow existing coding standard.
## Disclaimer
This project demonstrates usage of Google's private API but is not affiliated with Google. Use at your own risk.