Create a video generation task

For file inputs, upload through the Files API, then reference the returned file_id. The gateway converts the input; provider acceptance is determined upstream.

Reference assets with input_references: [{"type":"image","role":"reference","source":{"type":"file","file_id":"..."}}]. Type must match the image/audio/video file. The gateway reads the file and passes it to the selected provider in the form its API expects, keeping the role unchanged. Existing required fields remain required. For Images, Video and Speech, input_references is an InOneAPI extension.

Use POST /v1/videos, then poll the returned task ID. The complete examples enumerate the public fields, not a combination supported by every model. Remove optional fields that your selected model does not support.

Minimal request

Replace YOUR_MODEL_ID with the exact model detail ID; do not add a provider prefix. Optional parameters depend on the selected model. App attribution headers are commented out.

# -H "X-APP-NAME: Your App Name"
# -H "X-APP-URL: https://your-app.example.com"
curl "https://api.inoneapi.com/v1/videos" \
  -H "Authorization: Bearer $INONEAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "YOUR_MODEL_ID",
  "prompt": "A white cat running beside the sea"
}'

Authentication and headers

Send a server-side API key in Authorization: Bearer and Content-Type: application/json. X-Gateway-Trace-ID identifies the gateway request, not the video task. Never expose keys in browser code.

Complete request examples

curl --request POST 'https://api.inoneapi.com/v1/videos' \
  --header "Authorization: Bearer $INONEAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "model": "YOUR_MODEL_ID",
  "prompt": "A white cat running beside the sea",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "input_references": [
    {
      "type": "image",
      "role": "first_frame",
      "source": {
        "type": "url",
        "url": "https://example.com/start.png"
      }
    }
  ],
  "options": {
    "seed": 42,
    "negative_prompt": "blur",
    "generate_audio": true
  },
  "callback_url": "https://example.com/webhook"
}'

Parameter reference

Parameter	Type	Parameter reference
`model`	string	Required public InOneAPI model ID, not an internal provider ID.
`prompt`	string	Required subject, action, scene, camera, lighting and style description. Limits depend on the model.
`duration`	integer	Optional integer seconds, not milliseconds. Supported values and omitted defaults depend on the provider.
`resolution`	string	Optional resolution such as 720p or 1080p; availability may depend on duration and aspect ratio.
`aspect_ratio`	string	Optional width:height ratio such as 16:9, 9:16 or 1:1, not pixel dimensions.
`input_references`	array	Optional ordered media references; count and mixed-media support depend on the model.
`input_references[].type`	string	Required per item: image, video or audio.
`input_references[].role`	string	Required per item: first_frame, last_frame, reference or speech. Not every model supports every role.
`input_references[].source`	object	Required per item: source type plus the corresponding value.
`input_references[].source.type`	string	url, file (alias: file_id), or data. Specify exactly one source representation.
`input_references[].source.url`	string	Required for url: a provider-accessible HTTPS address. Signed URLs must remain valid until the provider reads them.
`input_references[].source.file_id`	string	Required for file/file_id: an InOneAPI Files API ID owned by this key. The gateway resolves it to a temporary URL the provider can read. Provider-side file IDs are not accepted.
`input_references[].source.data`	string	Required for data: provider-supported Base64 or data URL. No gateway transcoding.
`options`	object	Optional provider extensions. seed, negative_prompt and audio flags are examples, not universal fields. Only send options the model explicitly supports.
`callback_url`	string	Optional HTTPS callback, only when the provider supports callbacks. The gateway does not dispatch, sign or retry callbacks.

Media and capability boundaries

For text-to-video, omit input_references. For image-to-video use first_frame; first/last-frame generation requires both roles. Video and speech references require explicit model support. URL, file_id and data are alternative sources. The platform only reads the value you provide: it does not upload, download, resize or validate media. An options object is not automatic compatibility with arbitrary vendor parameters.

Responses and errors

The gateway wraps each new task ID in a signed ioa_v1. handle bound to your account, the public model and the provider that accepted the task. The value below is illustrative: preserve the complete returned ID and supply the original model when querying.

{"id":"ioa_v1.REPLACE_WITH_RETURNED_TASK_ID","status":"queued","created_at":"2026-09-05T08:30:00Z"}

id, status and created_at are normalized from the provider response. Missing provider timestamps are not synthesized. Creation can already return running, not only queued. Never fabricate success or status values. HTTP errors differ from a task whose status is failed. A creation timeout has an ambiguous outcome: blindly retrying can duplicate tasks and charges. Generic idempotency is not implemented.

GET /v1/videos/{id}