Video Generation API

The Video Generation API creates asynchronous video jobs. A create request returns HTTP 202 with a job ID; use that ID to poll until the job reaches succeeded or failed, then download the completed MP4.

The examples use https://api.icodeeasy.cc as the base URL. Every endpoint call documented below requires your API key; a signed result-file URL returned after success is the only exception:

Authorization: Bearer <your API key>

Endpoints

The status_url and content_url in create and status responses are canonical paths relative to the base URL; use them directly. The read-only compatibility routes GET /v1/videos/generations/{id} and GET /v1/videos/generations/{id}/content also read the same job. These compatibility paths do not accept creation or deletion.

Five-minute quickstart

1. Create a job

curl -X POST https://api.icodeeasy.cc/v1/videos/generations \
  -H 'Authorization: Bearer <your API key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2.5",
    "prompt": "a futuristic city street in the rain, slow forward camera movement, neon reflections on wet pavement",
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 4,
    "generate_audio": true
  }'

Creation returns HTTP 202:

{
  "id": "vid_1785398400000000000",
  "task_id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "status": "queued",
  "model": "doubao-seedance-2.5",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:00:00Z"
}

Use task_id as the recommended job identifier for polling, downloading, and deletion; id remains available with the same value for compatibility. A 202 response means the job was accepted, not that the video is already complete.

2. Poll the job

Copy the task_id from the create response into TASK_ID:

TASK_ID='vid_1785398400000000000'
curl "https://api.icodeeasy.cc/v1/videos/tasks/${TASK_ID}" \
  -H 'Authorization: Bearer <your API key>'

Poll about once every 5 seconds. Do not create another job while the current one is queued or running.

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "status": "running",
  "model": "doubao-seedance-2.0",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:00:20Z",
  "progress": 42
}

progress is best-effort and may be absent. Treat status, not progress, as authoritative.

3. Download the video

After status becomes succeeded, the response includes url and the final cost_rmb:

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "status": "succeeded",
  "model": "doubao-seedance-2.0",
  "created_at": "2026-07-30T08:00:00Z",
  "updated_at": "2026-07-30T08:01:18Z",
  "progress": 100,
  "url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "cost_rmb": 0.528
}

Download through the canonical authenticated content route and follow redirects:

TASK_ID='vid_1785398400000000000'
curl -L "https://api.icodeeasy.cc/v1/videos/tasks/${TASK_ID}/content" \
  -H 'Authorization: Bearer <your API key>' \
  -o result.mp4

The content route supports HTTP Range and common conditional download headers. Requesting content before success returns 409 video_not_ready.

Job lifecycle and safe retries

Retry rules:

• After receiving HTTP 202, keep polling the returned task_id. Repeating the create request may create another job.
• Polling and download GET requests are safe to retry.
• A polling HTTP 404 does not mean generation failed and must not trigger resubmission. Keep the original job ID, check the returned status_url or use GET /v1/videos/tasks/{id}, and authenticate with a valid API key belonging to the job owner. The video may already have succeeded and settled; check Usage Details. If the job still cannot be read, give support its ID and submission time.
• If creation returns submission_unknown, do not submit another request. The job may already have been accepted; contact support with the request time, model, and prompt summary.
• After a confirmed terminal failed job, create a new job only when you intentionally want to generate another video.

Webhooks and callback_url are not supported. Poll the job endpoint instead.

Create request reference

Put all text instructions in prompt. Use content only for reference images and videos.

Reference-media list (content)

content is a list because one job may need a first and last frame, several unordered reference images, Seedance 2.5 reference videos, or one image plus one video for Motion Control. Put one HTTPS URL string directly in each item's image_url or video_url field.

[
  { "type": "image_url", "image_url": "https://cdn.example.com/first.png", "role": "first_frame" },
  { "type": "image_url", "image_url": "https://cdn.example.com/last.png", "role": "last_frame" }
]

• Image types: image_url or input_image.
• Video types: video_url or input_video.
• Frame roles: first_frame and last_frame. For frame-guided generation, a last frame requires a first frame.
• Seedance 2.5 reference-video role: reference_video; accompanying ordinary reference images use reference_image.
• Motion roles: one reference_image and one reference_video.
• Grok reference images have no role; reference_image is also accepted.
• Reference audio is not currently supported.
• Media must use a publicly reachable HTTPS URL that remains valid while the job reads it.
• Put images in image_url and videos in video_url.

Complete first-frame and last-frame request

Host both images at publicly readable HTTPS URLs, then put the URLs directly in content:

curl -X POST https://api.icodeeasy.cc/v1/videos/generations \
  -H 'Authorization: Bearer <your API key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "doubao-seedance-2.0",
    "prompt": "the camera moves smoothly from the opening frame to the ending frame",
    "content": [
      {"type":"image_url","image_url":"https://cdn.example.com/first.png","role":"first_frame"},
      {"type":"image_url","image_url":"https://cdn.example.com/last.png","role":"last_frame"}
    ],
    "resolution": "480p",
    "ratio": "9:16",
    "duration": 4,
    "generate_audio": true
  }'

In frame-guided generation, you may send only the first frame. A last frame requires a first frame in the same request.

Model cookbook

Seedance: text, first frame, and last frame

Seedance 2.5, Seedance 2.0 Standard, Fast, Mini, and Seedance 1.5 Pro support text-to-video and first/last-frame generation. When using only images for guidance, reference images require explicit frame roles. Seedance 2.5 also supports the reference-video mode below.

{
  "model": "doubao-seedance-2.5",
  "prompt": "the camera circles a glass sculpture as morning light changes",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/seedance-first.png", "role": "first_frame" },
    { "type": "image_url", "image_url": "https://cdn.example.com/seedance-last.png", "role": "last_frame" }
  ],
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": 6,
  "generate_audio": true
}

Seedance 2.5 text-to-video defaults to 480p, 9:16, 4 seconds, and generated audio enabled. First-frame or first/last-frame mode without reference videos follows the first image's aspect ratio: set ratio to adaptive or omit it; the aspect_ratio alias follows the same rule. An explicit fixed ratio such as 16:9 returns 400 invalid_request instead of being silently rewritten. A portrait first frame produces portrait video. For 16:9 output, crop or expand the first image to 16:9, then use adaptive. Text-to-video and reference-video mode still accept fixed ratios such as 16:9.

Seedance 2.5: reference videos

Send the following JSON to POST https://api.icodeeasy.cc/v1/videos/generations with Authorization: Bearer <your API key> and Content-Type: application/json:

{
  "model": "doubao-seedance-2.5",
  "prompt": "Follow the motion in @Video1 to generate a smooth video",
  "content": [
    { "type": "video_url", "video_url": "https://cdn.example.com/reference.mp4", "role": "reference_video" }
  ],
  "resolution": "480p",
  "ratio": "9:16",
  "duration": 4,
  "generate_audio": true
}

Replace the example URL with a publicly readable HTTPS video URL. Pass a URL string directly in video_url; duration is the output duration. The service reads the reference-video duration, so no input-duration field is needed. Add multiple videos to content, each with reference_video; @Video1, @Video2, and so on in the prompt refer to videos in list order.

• Input: up to 10 MP4/MOV videos, 2–30 seconds each, at most 30 seconds total, and at most 100 MiB per file.
• Output: 4–30 seconds at 480p or 720p. You may set ratio and generate_audio; do not use Motion Control-specific options.
• You may also supply up to 2 images with type: "image_url", an image_url string, and role: "reference_image". Images in this mode are ordinary references with no guaranteed first or last frame; frame roles are also treated as ordinary references.
• Videos must use H.264/H.265 at 24–60 fps, with width and height each 300–6000 pixels, 409,600–8,295,044 total pixels (width × height), and a width/height ratio of 0.4–2.5. 720×720 meets these dimension limits.

After creation succeeds, poll the same job using the returned status_url or GET /v1/videos/tasks/{id}. Downloading works the same as for other models. Reference-video fees include reference input and output; see Billing below.

MiniMax H3: text, first frame, and last frame

MiniMax-H3 supports text-to-video and first/last-frame generation through the same public request. It accepts 768P or 2K, durations from 4 to 15 seconds, and the 21:9, 16:9, 4:3, 1:1, 3:4, and 9:16 ratios. Its defaults are 768P, 9:16, and 5 seconds. Do not send generate_audio: this public contract has no generated-audio request toggle for H3.

Kling: frame-guided generation

{
  "model": "kling-v3",
  "prompt": "a train enters the station through light fog",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/kling-first.png", "role": "first_frame" },
    { "type": "image_url", "image_url": "https://cdn.example.com/kling-last.png", "role": "last_frame" }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true
}

Important Kling differences:

• kling-v2-6: a last frame requires 1080p; generated audio is available only at 1080p and cannot be combined with a last frame.
• kling-3.0-turbo: first frame only; no generated audio.
• kling-v3 and kling-v3-omni: first/last frames and generated audio are supported.
• kling-v3-omni also accepts up to two roleless reference images, but do not mix roleless and frame-role images in one request.
• kling-video-o1: first/last frames; no generated audio.

Grok: unordered reference images

Grok accepts up to seven reference-image URLs. Do not assign first_frame or last_frame roles.

{
  "model": "grok-imagine-1.5-video",
  "prompt": "clouds roll over a canyon while the camera rises",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/grok-reference.png" }
  ],
  "resolution": "480p",
  "ratio": "16:9",
  "duration": 6
}

Grok defaults to 480p, 9:16, and 6 seconds. Generated audio is not supported.

Kling Motion Control

Provide one public HTTPS image and one public HTTPS MP4 video:

{
  "model": "kling-v3-motion-control",
  "prompt": "preserve the character identity and follow the reference motion",
  "content": [
    { "type": "image_url", "image_url": "https://cdn.example.com/character.png", "role": "reference_image" },
    { "type": "video_url", "video_url": "https://cdn.example.com/motion.mp4", "role": "reference_video" }
  ],
  "motion_mode": "std",
  "character_orientation": "image",
  "keep_original_sound": true
}

• character_orientation: "image": reference video must be 3–10 seconds.
• character_orientation: "video": reference video must be 3–30 seconds.
• Do not send resolution, ratio, duration, or generate_audio with a Motion Control model.

Model capability table

For standard models, omitted option values use each model's defaults shown above. model itself is always required. The service validates combinations before starting the job.

Response and download behavior

All job responses use this shape:

Prefer GET /v1/videos/tasks/{id}/content instead of storing assumptions about the returned URL shape. Use -L or enable redirects in your HTTP client. The authenticated content endpoint can return 200, 206 Partial Content, or a redirect to relay-managed storage.

A signed relay file URL can be opened without an API key; possession of the complete URL grants access to that video. Do not expose it in public logs, pages, or client-side analytics.

Deleting a safe terminal job returns HTTP 204 and may also remove its relay-managed video file. Download and store any result you need before deleting the job. Deletion is rejected with 409 video_delete_unsafe while a job is running or billing is unsettled. Deleting a local job record does not cancel generation that has already started.

Error handling

HTTP errors use:

{
  "error": {
    "type": "invalid_request",
    "message": "model is not supported"
  }
}

A failed job response may look like:

{
  "id": "vid_1785398400000000000",
  "object": "video.generation.job",
  "status_url": "/v1/videos/tasks/vid_1785398400000000000",
  "content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
  "status": "failed",
  "model": "doubao-seedance-2.0",
  "error": { "code": "generation_failed" }
}

Billing

Video generation uses account balance, not monthly quota.

ordinary video task price = displayed RMB price per second for the selected model/specification × billable seconds

Check the current per-second prices on the Pricing page. Resolution, generated audio, or Motion Control mode may select a different displayed per-second row. For standard models without reference videos, billable seconds are the requested duration; for Motion Control, they are the detected reference-video duration rounded up to a whole second. Seedance 2.5 reference videos use the reservation and actual-charge rules below, rather than output seconds alone.

Creation reserves the quoted amount and deducts it from the available balance, so the balance decreases while generation is still running. Insufficient balance returns 402 before generation starts. Success settles the final charge, settles any difference from the reservation, and writes the Usage Details entry; cost_rmb is the final charge. A definitely failed job refunds its entire reservation. The balance difference between adjacent request entries can include video reservations or refunds and is not necessarily the charge for that request.

Seedance 2.5 reference-video billing

Reference-video mode reserves an estimate using “total reference-video duration rounded up to a whole second + output seconds” and the reference-video estimate rate on the Pricing page. For example, a 2-second reference video generating 4 seconds of output reserves an estimate for 6 seconds; this is not a guaranteed final price.

The final charge follows actual usage: any amount below the reservation is refunded, and any amount above it is additionally deducted. cost_rmb and Usage Details show the final charge. A confirmed failure refunds the entire reservation. If progress stays at 99%, the job may be waiting for billing settlement; keep polling the original job and do not submit again.

Kling 4

kling-v4: 720p / 1080p, integer durations 3–30 seconds (default 5), audio always on; generate_audio: false is rejected locally. Only this model accepts omni_reference_task_type: auto / reference / edit / extend. Ratios: 16:9 / 9:16 / 1:1 / 21:9, plus auto in reference mode; omit ratio for extend. Supports first/last frames, up to 8 reference images and 5 videos; each video is 3–30 seconds, 30 seconds total. Edit/extend accept one video. If edit omits duration, it follows the input video duration rounded up; other modes default to 5 seconds. All media, including first/last frames, use owned asset_id references: first upload multipart kind=image or kind=video and file to POST /v1/videos/assets, then use the returned id in the generation request. Raw image/video URLs, audio references, and advanced intermediate frames are unavailable. Extend may supply a target last frame without a first frame.

Reference prices: ordinary 720p ¥1.0486/s, 1080p ¥1.5729/s; video input 720p ¥0.62916/billable second, 1080p ¥0.94374/billable second. Reference/edit with video bills output seconds + max(output seconds, rounded-up total input seconds); extend bills only added seconds.

{
  "model": "kling-v4",
  "prompt": "Preserve the subject and change the setting",
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true,
  "omni_reference_task_type": "edit",
  "content": [
    {
      "type": "video_url",
      "role": "reference_video",
      "asset_id": "vasset_uploaded_video"
    }
  ]
}

Expanded video models

Upload every new-model input as your own asset_id. Site limits: images up to 10 MB each, videos at least 3 seconds and up to 100 MiB. Vidu Q4 audio references and Omni Ext video inputs are unavailable in this release. Output audio controls are separate from audio references.

FLUX3 Video

FLUX3 supports text, image and single-video editing, 5–20 seconds (default 5); hd / fhd, ratios auto,21:9,2:1,16:9,4:3,1:1,3:4,9:16. Up to 10 ordered images: first → intermediate reference_image → last; preserve duplicates and order. One video, 3–30 seconds. draft: true is HD only. Modes: auto/t2v/i2v/v2v/draft_enhance. Output audio defaults on and may be disabled at the same reference price.

Use “Generate full / Enhance” on a completed site FLUX3 draft in history. Send only model, generation_mode: draft_enhance, site-owned source_task_id, and resolution; no new prompt, media, duration or audio. The source must be your own same-model successful settled draft. Draft fees are not credited.

Vidu

Vidu Q4: one first frame (optional prompt) or 1–15 references (required prompt, up to 20000 characters), no text-only or last frame. One reference_image explicitly selects reference mode; do not mix it with a first frame. 3–16 seconds; 540p/720p/1080p/2K/4K. Q3 requires 1–7 references and a prompt up to 5000 characters, 3–16 seconds; Mix allows 1–16 seconds and only 720p/1080p. Pro/Turbo support text-only, one first frame or first+last frames, 1–16 seconds, 540p/720p/1080p. Text-only requires a prompt up to 2000 characters; image prompts are optional. All five default to 720p and 5 seconds. Reference and text modes accept 1:1/9:16/16:9/3:4/4:3; first-frame generation follows its image and omits ratio. Q3/Mix have no audio switch; Q4/Pro/Turbo default audio on and allow off at the same reference price.

Gemini Omni

Gemini Omni main gemini-omni-1.1-flash: 360p/720p/1080p/4k, 16:9/9:16, up to 10 images with first/last or ordinary references, and one 3–10 second video. Preview: 720p only, up to 16 ordinary references, one 3–24 second video; no first/last-frame mode, omit ratio for video input. Output length follows the prompt (3–10 seconds): never send duration, generate_audio, seed, negative prompt or count. Output reference prices exclude possible media/context usage and are not a cost cap; settlement follows actual usage.

Use “Continue generation” on your own successful settled same-model main/Preview job in site history. A new prompt is required; source_task_id and video input are mutually exclusive. Never enter supplier task IDs. Modes: auto/t2v/i2v/reference/edit/extend.

Omni Ext: 360p/720p/1080p/4k, 16:9/9:16, 4/6/8/10 seconds (default 6), priced per clip. Text-only, one first frame, or exactly 1/3 reference images; no two-frame first/last, video input or source continuation. Prompt required; modes auto/t2v/frame/reference; omit audio parameters.

FLUX3 and Omni main/Preview show reference output prices; actual task charges take priority and media/context may add usage. Funds are reserved, then differences are refunded or additionally charged. Progress at 99% may await settlement: keep polling the original task, do not resubmit.

Final RMB reference price (per second)

Omni Ext final RMB reference prices (per clip)