Video API guide
Video generation is asynchronous: submit a prompt and optional references, save the task ID, poll status, then download the completed video. HTTP 200 means the request succeeded, not that generation is complete.
Preparation and parameters
Choose a public model with a video mapping and replace YOUR_MODEL_ID. Set INONEAPI_API_KEY on the server. Start with a text-only request before adding model-supported parameters.
| Parameter | Meaning |
|---|---|
model, prompt | Required public model ID and scene description; describe subject, movement, camera, and light. |
duration | Optional integer seconds; supported values vary. |
resolution | Such as 720p/1080p, only when supported. |
aspect_ratio | Such as 16:9/9:16, not pixel dimensions. |
input_references | Optional image/video/audio references with roles. |
options | Only extensions explicitly supported by the mapping; seed and negative prompts are not universal. |
callback_url | Only with provider and mapping support; the gateway does not send callbacks itself. |
Create and poll
The Node.js 20+ example creates a task and polls every 3 seconds for up to 10 minutes. Persist the full task ID and model in production. Set INONEAPI_VIDEO_TASK_ID on a subsequent run to resume without creating another task; keep the original model too.
curl https://api.inoneapi.com/v1/videos \
-H "Authorization: Bearer $INONEAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"YOUR_MODEL_ID","prompt":"A slow camera movement across a sunlit modern library"}'The example stops on non-2xx responses and keeps the printed task ID; it never automatically recreates a task. On query 429, wait according to Retry-After; use bounded backoff for temporary 5xx, then query the same ID. Adjust the overall deadline for the model.
Task states
| status | Meaning | Action |
|---|---|---|
queued | Waiting | Poll after a delay. |
running | Generating | Poll after a delay. |
succeeded | Complete | Check video_url and save promptly. |
failed | Generation failed | Stop and inspect error. |
cancelled | Cancelled | Stop; this does not imply a platform cancellation API. |
expired | Expired | Stop. |
States are normalized by the provider mapping. Creation may already return running. Treat unknown states as protocol problems rather than waiting forever. Mapped created_at and completed_at are ISO 8601 strings, not Unix seconds.
Image-to-video and references
Upload the first-frame image with the Files API, then submit this body with the same key. Size, duration, and roles are examples and must match supported combinations:
{
"model": "YOUR_MODEL_ID",
"prompt": "Slowly move the camera forward while preserving the reference scene.",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"input_references": [
{
"type": "image",
"role": "first_frame",
"source": {
"type": "file",
"file_id": "file_ioa_0123456789abcdef0123456789abcdef"
}
}
]
}Use first_frame for the initial image, last_frame for the final image, reference for reference media, and speech for speech, only when supported. Select exactly one source: file (alias file_id), url, or data. The gateway expands file IDs to private COS signed URLs; it does not transcode or validate provider role support.
Public files use a one-day COS lifecycle and signed URLs last 5 minutes. Providers must fetch while valid. Do not delete references before the provider has read them.
Task IDs, access, and routing
New tasks return signed handles beginning with ioa_v1.. Treat the full value as opaque, preserve it, and URL-encode it; do not parse, truncate, or replace it with an upstream ID. Queries require the original model and a valid key owned by the same user with model access. Creation with file references must also use the uploading key.
Handles bind the original mapping, upstream credential, user, and public model. Queries return to that mapping and credential; if unavailable, they do not automatically switch providers. Invalid signatures or user/model mismatches return VIDEO_TASK_NOT_FOUND. Legacy raw task IDs lack the same binding guarantees; retain their original upstream configuration during migration.
Save results and recover
Provider video_url values may expire and are not permanent hosting. Save to your storage promptly. Do not attach the InOneAPI key when downloading external assets; preserve direct browser download links.
A create timeout may occur after a task starts, and there is no general idempotency guarantee. Do not POST again because polling failed. Stopping local polling does not cancel generation. Save model, task ID, and X-Gateway-Trace-ID for recovery.
For 401/403, check access; for 404, check handle, owner, model, and upstream task; for 503, check the original mapping or credential. The gateway does not provide universal cancellation, video download proxying, callback signatures, or callback retries.