Video generation

POST /v1/videos

Asynchronous video generation. Rendering takes a while (typically tens of seconds to a few minutes), so it uses a submit + poll model: submit returns a task ID immediately, then you poll for the result.

Supports text-to-video, image-to-video (single-image first frame / first-and-last frame / multi-image reference), plus reference video and reference audio for advanced use.

Seedance 2.5

Use doubao-seedance-2-5 (720p) or doubao-seedance-2-5-1080p (1080p) with the same POST /v1/videos and task polling endpoints.

seconds accepts strings "4"–"30", or "0" for automatic duration. Inputs allow 30 images, 10 videos and 10 audio files, up to 50 items total, using downloadable HTTPS URLs. Images also accept PNG/JPEG/WebP base64 data URLs, converted by the gateway. Video/audio data URLs and asset:// are unsupported. First-frame and first/last-frame modes require aspect_ratio:"adaptive" (the 2.5 default); omit a fixed pixel size. output_format accepts mp4 or mov; generate_audio defaults to true in this gateway.

You may supply native mode and media instead of the legacy reference fields. Modes are TEXT_TO_VIDEO, IMAGE_TO_VIDEO, FIRST_LAST_FRAME, REFERENCE_MATERIAL, VIDEO_EDIT and VIDEO_EXTEND. Media objects contain type, role and url. Editing requires seconds:"0"; editing and extension require aspect_ratio:"adaptive". Never mix media with legacy reference fields.

Settlement uses actual output tokens. Official USD list prices per million tokens without/with video input: 720p $10.70 / $6.40; 1080p $11.70 / $7.00. Subscription and channel multipliers still apply.

1. Submit: POST /v1/videos

1.1 Request parameters

Video generation requires an active subscription (token-based billing, see 3. Billing). Without one the API returns 402.

Materials and limits: 2.5 allows 50 materials in total. Use directly downloadable HTTPS URLs; images also accept data:image/png;base64,..., JPEG or WebP (decoded image ≤ 10 MiB; whole JSON request ≤ 15 MiB). The gateway converts inline images, with no separate customer upload. Video/audio references cannot use data:. asset:// remains overseas -hw only. Resolution: both 2.0 and 2.5 pin 720p/1080p to the model ID. A cross-tier size / resolution returns 400; explicit aspect-ratio precedence does not override the model resolution tier.

1.2 Models

There are two product lines: a domestic line and an overseas line (-hw suffix), with independent capabilities and pricing. The overseas line supports the virtual-character asset library (asset://); the domestic line does not. Per-model prices are in the console model catalog.

1.3 Value ranges

Portrait text-to-video / multi-image reference (excluding 2.5 first/last-frame modes): send size:"720x1280" (recommended), or the equivalent aspect_ratio:"9:16" + resolution:"720p". If both are sent, the explicit aspect_ratio / resolution wins. Image-to-video: send image_url (single) or reference_image_urls (multiple), and refer to the image as @Image1 in prompt — otherwise the model won't condition on the reference image.

2.5 media modes (when using them, omit image_url, reference_*, audio_url and video_config):

1.4 @ reference syntax

With reference assets, the model relies on @ImageN / @VideoN / @AudioN in prompt to know each asset's role. Assets are cited by type + index (e.g. Image 1 / Video 1 / Audio 1), numbered by their order of appearance in the request:

• @Image1 = reference_image_urls[0] (or image_url for a single image), @Image2 = reference_image_urls[1], and so on
• @Video1 = reference_videos[0], and so on
• @Audio1 = reference_audios[0], and so on

With multiple assets you must reference them explicitly via @, otherwise the model guesses which image is which.

1.5 Virtual-character asset library

Besides https:// URLs and base64 data: URLs, the reference-image fields also accept asset://<asset ID> references — virtual-character material that is private to your org and that you upload beforehand to your own asset library. Upload it first via the asset library API to obtain an asset:// ID, then reference it in the video request:

{ "image_url": "asset://asset-20260713-xyz" }

Rules:

• Assets are private to your org: only the creating org can reference its own asset:// IDs; referencing another org's (or a nonexistent) ID returns 400. See the asset library API to upload / list / delete.
• An asset:// reference may go in image_url or as any item of reference_image_urls, and can be mixed with plain URLs / data URLs (e.g. "library character + your own scene image").
• An asset:// item is always treated as a character reference — even in the image_url field it is not used as a first frame. For first-frame semantics, use a plain URL / data URL.
• In prompt, refer to it as @ImageN per 1.4 @ reference syntax — numbering works exactly like regular reference images (by order of appearance in the request).
• Like regular reference images, asset references do not add billed tokens, and they count toward the "up to 9 reference images" limit.
• Overseas line (-hw series) only: doubao-seedance-2-0-hw / -1080p-hw / -fast-hw. The domestic line (doubao-seedance-2-0 / -1080p) does not support asset://.

1.6 Response

A successful submit returns immediately (task queued, video not produced yet):

{ "id": "task_xxxxxxxx", "status": "queued", "seconds": 5 }

Use the id field as the task ID for polling.

A successful submit is not a produced video. A queued task can still fail (e.g. content-safety rejection); wait for a terminal state via polling.

1.7 Examples

Seedance 2.5 image-to-video (material determines ratio)

{"model":"doubao-seedance-2-5","prompt":"@Image1 moves slowly","seconds":"5","aspect_ratio":"adaptive","image_url":"https://example.com/start-frame.jpg","generate_audio":true}

Text-to-video (size only, standard usage)

Sending size alone is enough to fix both orientation and resolution — no need to also send aspect_ratio / resolution:

curl https://api.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "a red fox running in snow, cinematic",
    "seconds": "10",
    "size": "720x1280"
  }'

Text-to-video (landscape)

curl https://api.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-1080p",
    "prompt": "A cinematic tracking shot through a neon-lit rainy street at night, slow dolly-in, 35mm grain",
    "aspect_ratio": "16:9",
    "size": "1920x1080",
    "seconds": "10"
  }'

Text-to-video (portrait)

curl https://api.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "a red fox running in snow, cinematic",
    "seconds": "10",
    "aspect_ratio": "9:16",
    "resolution": "720p",
    "size": "720x1280"
  }'

Image-to-video (single-image first frame)

The reference image may be an https:// URL or a base64 data: URL. The prompt must refer to it as @Image1.

curl https://api.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "@Image1 as the first frame, slow camera push-in, the character turns to look into the distance",
    "seconds": "10",
    "size": "720x1280",
    "image_url": "https://example.com/start-frame.jpg",
    "video_config": { "reference_mode": "start_frame" }
  }'

Image-to-video (multi-image: character + setting)

curl https://api.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "@Image1 character wearing a white dress, dancing in the setting from @Image2, anamorphic lens",
    "aspect_ratio": "21:9",
    "resolution": "720p",
    "seconds": "15",
    "reference_image_urls": [
      "https://example.com/character.jpg",
      "https://example.com/setting.jpg"
    ]
  }'

Image-to-video (first + last frame: exactly 2 images)

curl https://api.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "Smoothly transition from the first frame to the second, with natural camera movement and lighting changes",
    "seconds": "10",
    "size": "1280x720",
    "reference_image_urls": [
      "https://example.com/start-frame.jpg",
      "https://example.com/end-frame.jpg"
    ],
    "video_config": { "reference_mode": "start_end" }
  }'

Virtual-character asset library (asset:// reference)

Mixing a library character with your own scene image — @Image1 refers to the asset, @Image2 to the scene. The model must be an overseas -hw name (the domestic line does not support asset://):

curl https://api.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-hw",
    "prompt": "@Image1 character standing in the setting from @Image2, waving at the camera and smiling, natural light",
    "seconds": "5",
    "size": "1280x720",
    "reference_image_urls": [
      "asset://asset-20260713-xyz",
      "https://example.com/scene.jpg"
    ]
  }'

Omni reference (image + video + audio)

In 2.0, audio_url / reference_audios require an image or video; 2.5 also permits audio-only references.

curl https://api.aiin1.ai/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0",
    "prompt": "@Image1 character dancing to the rhythm of @Audio1, camera motion referencing @Video1, cut on strong beats",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "size": "1280x720",
    "seconds": "10",
    "reference_image_urls": [
      "https://example.com/character.jpg",
      "https://example.com/scene.jpg"
    ],
    "reference_video": "https://example.com/camera-motion.mp4",
    "reference_videos": ["https://example.com/camera-motion.mp4"],
    "audio_url": "https://example.com/track.mp3",
    "reference_audios": ["https://example.com/track.mp3"]
  }'

2. Poll: GET /v1/videos/{id}

curl https://api.aiin1.ai/v1/videos/task_xxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

status goes queued → processing → completed (or failed). Rendering is slow; poll every few seconds.

In progress:

{ "id": "task_xxxxxxxx", "status": "processing" }

Completed:

{
  "id": "task_xxxxxxxx",
  "status": "completed",
  "video_url": "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
  "usage": { "total_tokens": 108900 }
}

Failed:

{ "id": "task_xxxxxxxx", "status": "failed" }

About video_url: on completion you get a download link with limited validity — download or re-host it promptly. For a reliable way to fetch the file, prefer the /content endpoint below.

Field reference

Download the video: GET /v1/videos/{id}/content

Besides the video_url convenience field in the poll response, you can also fetch the raw video bytes directly from a standard endpoint (compatible with the OpenAI SDK's .download_content()). Only available once the task is completed:

curl https://api.aiin1.ai/v1/videos/task_xxxxxxxx/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o output.mp4

Returns video bytes; MP4 normally uses Content-Type: video/mp4. A 2.5 MOV request returns the actual video format. Use whichever fits — video_url is convenient for direct distribution/preview but has limited validity; /content has no expiry concerns and is the recommended way to reliably fetch the video file in production.

3. Billing

• Billed by generated tokens: cost = generated tokens × the per-1M-token price. Per-model unit prices are listed in the console model catalog.
• 2.0 token estimates (actual settlement uses returned usage; 2.5 does not use a fixed per-second estimate): 720p ≈ 21,780 tokens per second of video (5s ≈ 108,900); 1080p ≈ 49,005 tokens/s (5s ≈ 245,025). The fast variants (doubao-seedance-2-0-fast / -fast-hw) use the same token count as 720p, at a lower unit price.
• Reference images do not add billed tokens. Requests containing a reference video do have the video's content added to the token count (e.g. a 5s reference video adds roughly 108,900 tokens), but the whole request is billed at the cheaper "with video input" per-1M-token unit price — both prices are visible in the console model catalog.
• The poll response includes usage.total_tokens, which is exactly what gets billed — use it to reconcile invoices.
• Settled when the video completes; failed / abandoned tasks are not billed.

4. Common errors