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 that supports video generation 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 the model explicitly supports; seed and negative prompts are not universal. |
callback_url | Only when the provider supports callbacks; the platform does not dispatch them. |
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 follow the provider response. Creation may already return running. Treat unknown states as protocol problems rather than waiting forever. created_at and completed_at appear only when the provider returns them; the platform does not convert timestamps, so do not assume Unix seconds or ISO 8601.
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. File IDs are resolved to temporary URLs the provider can read; the platform does not transcode or prevalidate role support.
Public API files are kept for one day and each temporary URL lasts 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 a provider-side task 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 user, public model and the provider that accepted the task. Queries return to that provider; if it is unavailable, they do not automatically switch to another. Invalid signatures or user/model mismatches return VIDEO_TASK_NOT_FOUND. Legacy raw task IDs lack the same binding guarantees; keep using their original lookup path 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 whether the provider that accepted the task is available. The gateway does not provide universal cancellation, video download proxying, callback signatures, or callback retries.