---
title: "Create video generation task"
method: POST
path: "/v1/videos/generations"
tags: ["Video"]
---

# Create video generation task

`POST /v1/videos/generations`

## Request

- Base URL: `https://api.tokenlab.sh`
- URL: `https://api.tokenlab.sh/v1/videos/generations`
- Auth: HTTP bearer

Creates an asynchronous video generation task. The response returns a canonical task ID and usually a preferred `poll_url`; clients should poll `poll_url` first, or use `/v1/tasks/{id}` as the fixed status endpoint.

## Headers

- `X-TokenLab-Delivery-Policy` 'auto' | 'verified' | 'official'

## Request body

- VideoGenerationRequest
  - `prompt` string: Video description
  - `model` string: Model to use (e.g., veo3.1, kling-v3.0)
  - `operation` 'text-to-video' | 'image-to-video' | 'reference-to-video' | 'start-end-to-video' | 'video-to-video' | 'video-extension' | 'audio-to-video' | 'motion-control': Requested video operation. If omitted, TokenLab infers the operation from the provided inputs. Explicit operation is recommended for production reliability.
  - `image` string: Inline image as a data URL (for example, data:image/png;base64,...). Prefer image_url for broader production compatibility. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.
  - `image_url` string, uri: Publicly reachable image URL for image-to-video generation, or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab Seedance material used as the first frame. Preferred over inline base64 in production. TokenLab verifies material ownership. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.
  - `video_url` string, uri: Publicly reachable video URL for video-to-video style flows and motion-control models.
  - `duration` integer: Video duration in seconds. Seedance models also accept -1 to let the model choose within its supported duration range; TokenLab estimates billing conservatively for that mode.
  - `aspect_ratio` 'adaptive' | '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '21:9': Canonical video aspect ratio. Seedance defaults to adaptive when omitted. The ratio alias is accepted for compatibility.
  - `resolution` '480p' | '720p' | '1080p' | '4k': Video resolution. Seedance defaults to 720p when omitted; available values are model-dependent.
  - `output_format` 'mp4' | 'mov': Video container format for compatible models. Seedance 2.5 supports mp4 and mov; omit this field for Seedance 2.0 and other models that do not publish an output-format selector.
  - `output_audio` boolean: Audio-output selector for operations that declare it. Omission follows the model default; `false` requests silent output only when allowed. See the audio behavior above and the selected model detail.
  - `fps` integer: Frames per second
  - `negative_prompt` string: What to avoid in the video
  - `seed` integer: Seed for reproducibility on compatible models. Compatible Seedance models use -1 for a random seed when omitted; Seedance 2.5 does not support this field.
  - `cfg_scale` number: Prompt adherence strength (0-20) for models that expose CFG-style control.
  - `motion_strength` number: Motion intensity (0-1) for models that expose it.
  - `start_image` string: First frame image input for start-end-to-video flows. Seedance accepts a public image reference or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab material owned by the requesting organization. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.
  - `end_image` string: Last frame image input for start-end-to-video flows. Seedance accepts a public image reference or asset://asset-YYYYMMDDHHMMSS-xxxxx for an ACTIVE TokenLab material owned by the requesting organization. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as a reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.
  - `user` string: End-user identifier
  - `image_urls` string[]: Image URL array for compatible image-conditioned video flows. Seedance 2.5 accepts up to 30 aggregate image inputs; other video models retain the shared limit of 9 entries unless the model details specify a lower limit. When the selected Seedance model can use the TokenLab material library, TokenLab prepares this image input as reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.
  - `kling_elements` object[]: Element references for image-conditioned requests on models that explicitly support this field. Define 1-3 elements and reference them in the prompt with @name. Each element requires 2-4 image URLs in element_input_urls. Do not combine kling_elements with output_audio=true; omit output_audio or set it to false for element-reference requests.
    - `name` string, required: Element name used in the prompt without the @ prefix.
    - `description` string: Optional short description of the element.
    - `element_input_urls` string[], required: Reference image URLs for this element. Kling 3.0 expects 2-4 images per element.
  - `reference_images` string[]: Canonical public reference-image field for reference-to-video conditioning. Seedance 2.5 accepts up to 30 aggregate image inputs; other video models retain the shared limit of 9 URLs or compatible data URLs unless the model details specify a lower limit. xAI grok-imagine-video accepts up to 7 image references with duration capped at 10 seconds; grok-imagine-video-1.5 and grok-imagine-video-1.5-preview are image-to-video only and do not accept reference images. When the selected Seedance model can use the TokenLab material library, TokenLab prepares ordinary image input as reusable material before generation; if it is not ACTIVE within 60 seconds, the API returns 409 seedance_material_preparing with auto_material_asset_ids. If the selected model cannot use the material library, ordinary image inputs continue on the regular image path.
  - `material_asset_id` string: TokenLab Seedance material asset ID returned by /v1/videos/assets, by automatic image preparation, or from a real-person group returned by GetVisualValidateResult. Use it after the asset is ACTIVE with Seedance models that can use the TokenLab material library. The asset must belong to the current account. This field is a generic reference input; to assign first-frame, last-frame, or reference-image semantics explicitly, put asset://<material_asset_id> in start_image, end_image, or reference_images.
  - `material_asset_ids` string[]: TokenLab Seedance material asset IDs returned by /v1/videos/assets or by automatic image preparation. They share the Seedance image-reference limit; the selected model must be able to use the TokenLab material library and all assets must belong to the current account and be ACTIVE.
  - `reference_image_type` 'asset' | 'style': Optional reference image role for models that distinguish between asset and style references. The camelCase alias referenceImageType is accepted for compatibility.
  - `audio_url` string, uri: Public audio URL for an audio-driven or reference-audio operation supported by the selected model.
  - `task_id` string: Task identifier used by some continuation, extension, or derivative flows.
  - `extend_at` integer: Model-specific extension start offset used by some video-extension flows.
  - `extend_times` string: Model-specific extension multiplier or repeat count used by some video-extension flows.
  - `seconds` integer: Alias of duration used by compatible request shapes. Seedance models also accept -1 to let the model choose within its supported duration range; duration and seconds must match when both are provided.
  - `size` string: Model-specific size tier for compatible video models.
  - `watermark` boolean: Optional watermark toggle for models that expose it. Seedance defaults to false when omitted.
  - `effect_type` string: Model-specific effect selector for specialized editing flows.
  - `video_urls` string[]: Compatibility array for video-conditioned flows when multiple input videos are supported by the selected model. Seedance 2.5 accepts up to 10 aggregate video inputs; other video models retain the shared limit of 3 references unless the model details specify a lower limit.
  - `audio_urls` string[]: Compatibility array for audio-conditioned flows when multiple audio references are supported by the selected model. Seedance 2.5 accepts up to 10 aggregate audio inputs and permits pure-audio reference requests without a prompt; other video models retain the shared limit of 3 references unless the model details specify a lower limit.
  - `ratio` 'adaptive' | '16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '21:9': Compatibility alias for aspect_ratio. If both ratio and aspect_ratio are provided, they must match.
  - `outputAudio` boolean: Compatibility alias for output_audio. If both are provided, they must match.
  - `generate_audio` boolean: Compatibility alias for output_audio. If more than one audio toggle is provided, all values must match.
  - `execution_expires_after` integer: Optional execution expiry window in seconds for compatible video models. Seedance defaults to 172800 seconds when omitted.
  - `priority` integer: Optional task priority for compatible video models. Do not combine priority with service_tier=flex.
  - `safety_identifier` string: Optional safety/user trace identifier for compatible video models. If omitted for Seedance, TokenLab uses user when provided.
  - `service_tier` 'default' | 'flex': Optional service tier for compatible video models. service_tier=default is accepted as a compatibility no-op for Seedance 2.0 and Seedance 2.5; service_tier=flex is rejected for both models.
  - `frames` integer: Optional frame count for compatible video models. Seedance 1.5 Pro, Seedance 2.0, and Seedance 2.5 do not support this field.
  - `camera_fixed` boolean: Optional fixed-camera selector for compatible video models. Seedance 2.0 and Seedance 2.5 do not support this field.
  - `return_last_frame` boolean: Return the last generated frame when the selected model supports it. Seedance defaults to false when omitted.
  - `draft` boolean: Seedance 1.5 Pro draft workflow flag. Only supported by Seedance models supporting drafts; draft=true creates a low-cost draft task.
  - `draft_task_id` string: Seedance 1.5 Pro draft promotion task ID. Provide this instead of draft=true to create the final video from a previous draft task.
  - `audio` boolean: Audio-output selector for operations that declare it. Omission follows the model default; `false` requests silent output only when allowed. See the audio behavior above and the selected model detail.
  - `bgm` boolean: Optional audio control. Accepted only when declared by the selected model and operation; availability may differ by operation.
  - `audio_type` string: Optional audio control. Accepted only when declared by the selected model and operation; availability may differ by operation.
  - `voice_id` string: Optional audio control. Accepted only when declared by the selected model and operation; availability may differ by operation.

## Response `200`

Task created successfully

- VideoGenerationResponse
  - `id` string, required: Task ID
  - `status` 'pending' | 'processing' | 'completed' | 'failed': Task status
  - `created` integer: Unix timestamp
  - `model` string
  - `video` object
    - `url` string
    - `duration` number
    - `width` integer
    - `height` integer
  - `error` union: Why the task failed: a string, or an object with `message` and, when known, `type`, `code`, `param` and `retryable`.
    - string
    - object
      - `message` string, required
      - `type` string
      - `code` string
      - `param` string
      - `retryable` boolean
  - `error_details` AsyncTaskErrorDetails: Why a task failed. A status read returns HTTP 200 even for a failed task; `status` here is the status of the failure itself.
    - `projection_version` integer: `2` means `message` is the final reason for the failure.
    - `status` integer, required
    - `message` string, required
    - `type` string, required
    - `code` string, required
    - `param` string: The request field at fault, omitted when no specific field is known.
    - `retryable` boolean, required
    - `upstream` AsyncTaskUpstreamError: The upstream service's own error, present only for a task that ran on an Official route. Its `code` values are defined by the upstream service and may change; branch on `error_details.code` and `error_details.type`.
      - `source` string: Upstream service name, when known.
      - `code` string
      - `message` string, required
      - `param` string
  - `task_id` string: Canonical async task identifier for polling. Treat this as the same identity as id when both are present.
  - `poll_url` string: Preferred polling URL for this task. Use this exact path when checking status.
  - `video_url` string: Generated video URL when the create response is already terminal or includes an immediate result.
  - `last_frame_url` string: Last generated frame URL when requested and supported by the selected model.
  - `content` object
    - `video_url` string
    - `last_frame_url` string
    - `file_url` string, nullable
  - `generate_audio` boolean: Resolved audio output flag when returned by the adapter.
  - `draft` boolean: Whether the Seedance draft workflow was used for this task.
  - `draft_task_id` string: Seedance draft task identifier when returned by the adapter.
  - `media_retention` MediaRetention: Saving status of the media results in this response. Present when the status is known within the response time limit; when it is absent, the media URLs still work.
    - `days` integer, required: Days a media-result URL stays valid after the result is first recorded.
    - `items` object[], required
      - `url` string, uri, required
      - `kind` 'image' | 'video' | 'audio' | '3d', required
      - `content_type` string
      - `status` 'saving' | 'saved' | 'failed' | 'expired', required
      - `expires_at` string, date-time, required

## Other responses

- `400`: Bad Request - Invalid input
- `401`: Unauthorized - Invalid or missing API key
- `402`: Payment Required - Insufficient balance or quota exceeded
- `409`: Seedance material is still preparing
- `429`: Rate Limit Exceeded
- `500`: Internal Server Error
- `503`: The requested Delivery tier is temporarily unavailable.

---

[API](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway.md) · [All operations](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/tokenlab/apis/tokenlab-ai-gateway/revisions/3208bfbcda22?raw)