Video Generation API
Submit asynchronous video-generation jobs, query their status, and retrieve generated content.
Video generation is asynchronous. The submission endpoint accepts a job and returns a public task object; generation, provider polling, and final settlement happen in the background.
Submit a job
The following three paths have the same behavior:
POST /v1/videosPOST /v1/videos/generationsPOST /v1/video/generations
Requests use application/json and Authorization: Bearer <API_KEY>.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | No | Specify a video model from the catalog explicitly; when omitted the gateway uses a built-in default. Check the catalog for currently available models. |
prompt | string | Conditional | Required for text-to-video; optional when media is provided. |
negative_prompt | string | No | Negative prompt. |
media | array | No | Media for image-to-video, first/last frames, video continuation, or editing. |
image | string | No | Compatibility alias for the first frame in media. |
duration | integer | No | Video duration in seconds. seconds is also accepted. |
resolution | string | No | For example, 1920x1080 or 1080P. size is also accepted. |
ratio | string | No | For example, 16:9, 9:16, 1:1, 4:3, or 3:4. |
fps | integer | No | Frame rate. |
audio_url | string | No | Driving-audio URL. |
reference_voice | string | No | Reference-audio URL. |
audio_setting | string | No | Audio setting for video editing, such as auto or origin. |
seed | integer | No | Random seed. |
response_format | string | No | url or b64_json, when supported by the model. |
user | string | No | Identifier for the end user. |
media[].type supports first_frame, last_frame, driving_audio, and first_clip. media[].url can be a public URL, a temporary object-storage URL, or a Base64 data URL. When the model requires source media, omitting required media returns 400 before task pre-authorization.
Request example
curl "${BASE_URL}/v1/videos" \
-H "Authorization: Bearer ${APIQIK_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"model": "<video-model-id>",
"prompt": "A slow camera push through a bamboo forest in the morning mist",
"duration": 5,
"resolution": "1920x1080",
"ratio": "16:9"
}'Submission response
{
"id": "video_01JEXAMPLE",
"object": "video",
"model": "<video-model-id>",
"status": "queued",
"progress": 0,
"created_at": 1789987200,
"seconds": 5,
"size": "1920x1080"
}The public id is only for gateway queries. Do not depend on its internal format. A failed submission does not return a queryable successful task.
Model selection
Entries whose capabilities include video in the model catalog can be used with this endpoint. Text-to-video, image-to-video, reference-to-video, video editing, duration and resolution tiers, and billing all depend on the target model; the console model details are authoritative, and this page does not list a fixed set.
Call GET /v1/public/models?availableOnly=true to see currently available video models.
Query a job
GET /v1/videos/{video_id}
The response remains an object with object: "video". Common statuses include queued, processing, completed, and failed. While processing, progress reports completion; a completed task can include completed_at and url. A failed task includes an error object:
{
"id": "video_01JEXAMPLE",
"object": "video",
"status": "failed",
"progress": 0,
"error": {
"code": "upstream_error",
"message": "video generation failed"
}
}Clients should poll with backoff and avoid frequent requests for unfinished jobs. Background task processing advances terminal states; the query endpoint is not a settlement endpoint.
Retrieve generated content
GET /v1/videos/{video_id}/content
On success, the endpoint redirects to the generated content URL. Clients should follow the 302 redirect and download the content from the redirected response. An unfinished or failed task, or an unavailable result, returns a structured error.
Billing and retries
Video submission pre-authorizes balance when the request is accepted; the background workflow settles or releases it based on the provider task state. If the submission response does not reach the client, do not blindly create a duplicate job. First investigate using the business-side X-Request-Id and task information.