Video modelsAdvanced usersUpdated
POST/v1/videos/generations
viduq4-preview
Request ID viduq4-preview
Protocols
POST /v1/videos/generations· Generate video exampleGET /v1/videos/tasks/{id}· Check video task exampleGET /v1/videos/tasks/{id}/content· Download video exampleDELETE /v1/videos/tasks/{id}· Delete a finished video task examplePOST /v1/videos/assets· Upload an asset exampleDELETE /v1/videos/assets/{id}· Delete an asset example
Authentication
Requests require an API key from API key management. For JSON requests, set Content-Type: application/json.
Authorization: Bearer YOUR_API_KEY
Request parameters
POST /v1/videos/generations
| Field | Type | Required | Description |
|---|---|---|---|
model | string | Required | viduq4-preview. Use the model ID shown on this page. |
prompt | string | Conditional | Describe the scene, action, and camera movement. Required for text or reference generation. Optional with a first frame. Up to 20000 characters. |
content | array<object> | Required | Required list of reference assets. Use one first frame or 1–15 general reference images. The two modes are separate. |
content[].type | string | Required | Accepted values are text, image_url, input_image. |
content[].text | string | Conditional | Provide the prompt when the content item has type: "text". |
content[].role | string | Conditional | Use first_frame for a starting image. Use reference_image for a general reference image. The role may be omitted for a general reference image. |
content[].asset_id | string | Conditional | Upload to POST /v1/videos/assets and use the returned id. Send kind (image) before file in the multipart form. |
resolution | string | Optional | Accepted values are 540p, 720p, 1080p, 2K, 4K. Default: 720p. |
ratio | string | Optional | Output aspect ratio. Also accepts the alias aspect_ratio. Accepted values are 1:1, 9:16, 16:9, 3:4, 4:3. Default: 16:9. Omit the ratio in first-frame mode. Output follows the image. |
duration | integer | Optional | Output length in seconds. Accepts whole seconds from 3 to 16. Default: 5. |
generate_audio | boolean | Optional | Whether to generate an audio track. Default: true. |
generation_mode | string | Optional | Accepted values are auto, i2v, r2v. Defaults to auto, which selects a mode from the inputs. An explicit mode must match the inputs. |
Request examples
Set your API key in the local ICODEEASY_API_KEY environment variable and choose an endpoint that accepts direct HTTP calls. For endpoints that require a specific client, follow that client’s setup guide.
Replace example media URLs and asset IDs with your own valid assets.
Video Generations
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/generations' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"model": "viduq4-preview",
"prompt": "Move the camera slowly toward the subject in the reference image.",
"resolution": "720p",
"ratio": "16:9",
"duration": 5,
"content": [
{
"type": "image_url",
"role": "reference_image",
"asset_id": "YOUR_IMAGE_ASSET_ID"
}
]
}'
Check video task
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY"
Download video
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID/content' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-L \
-o result.mp4
Delete a finished video task
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/tasks/YOUR_TASK_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-i \
-X DELETE
Upload an asset
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/assets' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-F 'kind=image' \
-F '[email protected];type=image/png'
Delete an asset
bash
curl -sS 'https://api.icodeeasy.cc/v1/videos/assets/YOUR_ASSET_ID' \
-H "Authorization: Bearer $ICODEEASY_API_KEY" \
-i \
-X DELETE
Responses and tasks
HTTP 202 · Task accepted
json
{
"id": "vid_1785398400000000000",
"object": "video.generation.job",
"model": "viduq4-preview",
"created_at": "2026-07-30T08:00:00Z",
"status_url": "/v1/videos/tasks/vid_1785398400000000000",
"content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
"status": "queued",
"updated_at": "2026-07-30T08:00:00Z",
"task_id": "vid_1785398400000000000"
}
HTTP 200 · Completed task lookup
json
{
"id": "vid_1785398400000000000",
"object": "video.generation.job",
"model": "viduq4-preview",
"created_at": "2026-07-30T08:00:00Z",
"status_url": "/v1/videos/tasks/vid_1785398400000000000",
"content_url": "/v1/videos/tasks/vid_1785398400000000000/content",
"status": "succeeded",
"updated_at": "2026-07-30T08:01:00Z",
"url": "/v1/videos/tasks/vid_1785398400000000000/content"
}
Save id. With the same API key, send GET requests to status_url until status is succeeded or failed. On success, download from content_url and follow HTTP redirects. Both paths are relative to the API base URL.
| Field | Type | Description |
|---|---|---|
id / task_id | string | Task ID. In the creation response, task_id equals id. |
status | string | Task state, one of queued, running, succeeded, or failed. |
progress | integer | Generation progress. Omitted when the service has no progress value. |
error.code | string | Error classification for failed tasks. |
Common errors
| HTTP | Error type | Description |
|---|---|---|
| 400 | invalid_request | Check the model, parameter combination, and reference media. |
| 401 | unauthorized | Check whether the API key is missing, invalid, or disabled. |
| 402 | insufficient_balance | The balance is insufficient to submit the task. |
| 404 | not_found | If polling returns 404, keep the task ID and check the polling URL and API key for the account that created the task. It may already have finished. Do not resubmit on this basis. |
| 409 | video_not_ready | The video is still being generated. Continue polling. |
| 503 | submission_unknown | The submission outcome is unknown. Contact support to check whether a task was created before sending a new request. |
Full integration guide · See the full API guide for request fields, task states, and response formats.
Capabilities and limits
text_to_video· Not supportedimage_to_video· Supportedfirst_frame· Supportedlast_frame· Not supportedreference_images· Supportedvideo_input· Not supportedaudio· Supported- Limits Resolutions: 540p, 720p, 1080p, 2K, 4K · Aspect ratios: 1:1, 9:16, 16:9, 3:4, 4:3 · Reference images: up to 15 · Durations: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 · Input: Site images ≤10 MB. No audio reference upload. No supplier task IDs.
Model Capability Catalog · View pricing
Related guides
Video Generation API
Create video tasks from text, first and last frames, or references; poll status, download results, and delete finished tasks when needed.
Model Capability Catalog
Compare public text, image, and video models by normalized request ID, compatible protocols, supported clients, tool use, media capabilities, limits, and review date.