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.5",
  "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.5",
  "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
}

Use content_url to download the video.

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

See Response and download behavior for status codes and redirects.

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

Reference-media list (content)

• Models that accept URLs. For example, Seedance 2.5 and Motion Control. Set image_url or video_url to a public HTTPS URL that stays reachable while the job reads it.
• Models that require uploads. Kling 4, Kling 4.0 Flash, FLUX3 Video, the Vidu Q3/Q4 and Gemini Omni models listed here use media uploaded by the same account. Upload reference media, then set each item's asset_id to the returned id.

This example uses URLs for the first and last frames.

[
  { "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.

Upload video reference media

In multipart uploads, kind must precede file. Set kind to image or video to match the uploaded file.

curl -sS https://api.icodeeasy.cc/v1/videos/assets \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -F 'kind=video' \
  -F '[email protected];type=video/mp4'

HTTP 201 returns the asset object. Pass its id in content[].asset_id when creating a job.

Delete video reference media

curl -i -sS -X DELETE 'https://api.icodeeasy.cc/v1/videos/assets/YOUR_ASSET_ID' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

Delete the asset with the owning account's API key. Success returns HTTP 204.

Response and download behavior

All job responses use this shape:

Download using content_url. The authenticated endpoint supports HTTP Range and common conditional headers. It can return 200, 206 Partial Content, or a redirect to Relay-managed storage. Configure your client to follow redirects. Before the job succeeds, the content route returns 409 video_not_ready.

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.

Delete a terminal job

curl -i -sS -X DELETE 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

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.5",
  "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.

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.

Kling 4

kling-v4: 720p / 1080p, integer durations 3–30 seconds (default 5), audio always on; generate_audio: false is rejected locally. Kling 4 models accept 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"
    }
  ]
}

Kling 4.0 Flash

Kling 4.0 Flash supports 720p, 3–20 seconds (default 5) and generated audio. Use omni_reference_task_type as above. For first-frame generation, send one first_frame and omit ratio; the output follows the image. Reference generation accepts up to 10 images and 5 videos, each 3–20 seconds with 20 seconds total. Edit takes one 3–20 second video, optionally with reference images. Extend takes one video and omits images and ratio; the result contains only the added segment. All media use owned asset_id values.

The 720p price is ¥0.66 per second for generation without input video and for the added segment when extending. Editing and generation with video references cost ¥0.440003 per billable second. In these modes the billed seconds include the output plus the larger of output duration and input duration rounded up.

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 are unavailable.

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 1.1 Flash

gemini-omni-1.1-flash

360p/720p/1080p/4k, 16:9 or 9:16, and 4/6/8/10 seconds (default 6). The prompt is required. Use text alone, one first frame, or exactly one or three reference images. Choose generation_mode from auto, t2v, frame, and reference. Omit audio settings. Last frames, input video, and task continuation are unavailable. Prices are per clip.

Gemini Omni Flash Preview

gemini-omni-flash-preview supports 720p, up to 16 ordinary reference images or one 3–24 second video. Omit ratio for video input. The prompt determines the 3–10 second output length. Omit duration, generate_audio, seed, negative prompt, and count.

To continue your own completed and settled Preview task, choose “Continue generation” in history and enter a new prompt. Use the site source_task_id or an input video. Modes are auto/t2v/i2v/reference/edit/extend.

FLUX3 and Gemini Omni Flash Preview show reference output prices. Media and context may add usage, and settlement follows the actual task charge. A task at 99% may be awaiting settlement. Keep polling its existing ID.

Gemini Omni 1.2 Flash

Gemini Omni 1.2 Flash supports 360p/720p/1080p/4k and 16:9 or 9:16, with a prompt in every mode. Use generation_mode set to auto for text or frames, or reference for up to 10 reference images. Send reference images separately from first/last frames. Output duration is 3–15 seconds (default 10); first-and-last-frame generation is limited to 3–10 seconds.

Use generation_mode: edit or extend with one owned MP4 or MOV asset_id (up to 15 seconds, 64 MB). Omit duration for editing; pricing follows the source duration. For extension, duration specifies 3–10 added seconds and only those seconds are billed. You can extend a completed same-model task you own with its site source_task_id instead of a video. Omit generate_audio.

Final RMB reference price (per second)

Gemini Omni 1.1 Flash final RMB reference prices (per clip)