DocumentationAccess MethodsImage / Video Tasks

Image / Video Tasks

Submit async image or video generation tasks and poll for results.

Endpoint

Submit image task	`POST /v1/image/generate`
Submit video task	`POST /v1/video/generate`
Query task	`GET /v1/image/generate/{'{taskId}'} · GET /v1/video/generate/{'{taskId}'}`

Authentication

Header Authorization: Bearer YOUR_API_KEY

Unified envelope with a result field and a message object (code, messageInfo); code=200 on success.

Submit image task curl example

curl https://your-router-domain.com/v1/image/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_IMAGE_MODEL",
    "prompt": "a cat sitting on a sofa",
    "num": 1,
    "size": "1024x1024",
    "aspectRatio": "1:1"
  }'

Submit video task curl example

curl https://your-router-domain.com/v1/video/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_VIDEO_MODEL",
    "prompt": "the character starts walking",
    "images": [
      { "url": "https://cdn.example.com/first.png", "type": "first" },
      { "url": "https://cdn.example.com/last.png",  "type": "last" }
    ],
    "duration": 5,
    "resolution": "720p",
    "aspectRatio": "16:9"
  }'

Query task curl example

# Query image task
curl https://your-router-domain.com/v1/image/generate/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

# Query video task
curl https://your-router-domain.com/v1/video/generate/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Query response

On submission, a result object containing taskId, type, model, status is returned with initial status=PENDING. Poll with taskId — when status=SUCCESS, results[] contains the output (image: url/width/height; video also includes previewImageUrl/fileSize). Time fields are millisecond timestamps. On failure, result is null and message.code≠200.

Input media type guide

images: first (first frame) · last (last frame) · ref (reference). For i2i image generation, type can be omitted. videos / audios: base (primary input) · ref (reference). taskType is inferred server-side from the inputs — no need to pass it.

Gemini Images Codex