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

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": "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": "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": "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.
• 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, 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. A last frame always requires a first frame.
• 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
  }'

You may send only the first frame. You cannot send a last frame unless the same request also contains a first frame.

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. Reference images require explicit frame roles. Seedance 2.5 is listed first in this family.

{
  "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": "16:9",
  "duration": 6,
  "generate_audio": true
}

Seedance 2.5 defaults to 480p, 9:16, 4 seconds, and generated audio enabled. With a first frame or first-plus-last frames, its ratio is normalized to adaptive.

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": "failed",
  "model": "doubao-seedance-2.0",
  "error": { "code": "generation_failed" }
}

Billing

Video generation uses account balance, not monthly quota.

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, billable seconds are the requested duration; for Motion Control, they are the detected reference-video duration rounded up to a whole second.

The balance must be able to cover the job when it is created. Insufficient balance returns 402 before generation starts. The successful job's cost_rmb is the authoritative final charge. A definitely failed job is not charged.