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 replaces source with a COS signed URL, preserves role, then applies DSL. Existing required fields remain required. For Images 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 and voices 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

ParameterTypeParameter reference
modelstringRequired public InOneAPI model ID, not an internal provider ID.
promptstringRequired subject, action, scene, camera, lighting and style description. Limits depend on the model.
durationintegerOptional integer seconds, not milliseconds. Supported values and omitted defaults depend on the provider.
resolutionstringOptional resolution such as 720p or 1080p; availability may depend on duration and aspect ratio.
aspect_ratiostringOptional width:height ratio such as 16:9, 9:16 or 1:1, not pixel dimensions.
input_referencesarrayOptional ordered media references; count and mixed-media support depend on the model.
input_references[].typestringRequired per item: image, video or audio.
input_references[].rolestringRequired per item: first_frame, last_frame, reference or speech. Not every model supports every role.
input_references[].sourceobjectRequired per item: source type plus the corresponding value.
input_references[].source.typestringurl, file (alias: file_id), or data. Specify exactly one source representation.
input_references[].source.urlstringRequired for url: a provider-accessible HTTPS address. Signed URLs must remain valid until the provider reads them.
input_references[].source.file_idstringRequired for file/file_id: an InOneAPI Files API ID owned by this key. The gateway resolves it to a COS signed URL. Upstream provider file IDs are not accepted.
input_references[].source.datastringRequired for data: provider-supported Base64 or data URL. No gateway transcoding.
optionsobjectOptional provider extensions. seed, negative_prompt and audio flags are examples, not universal fields. Only send explicitly mapped options.
callback_urlstringOptional HTTPS callback, only when supported and mapped by the provider. 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. media_source extracts a value only: 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 the user, public model, original mapping, and upstream credential. 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"}

Normalize id, status and created_at in the mapping. 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}

Create a video generation task · Documentation · InOneAPI