Create video

Submit a video generation task. The request returns 202 Accepted immediately with a task id and a polling URL — generation runs asynchronously. Poll the task or receive a webhook, then read the result with Get video status.


POST https://api.ofox.io/v1/videos

Request parameters

Parameter	Type	Required	Description
`model`	string	✅	Model slug, e.g. `bytedance/seedance-2.5` or `bytedance/seedance-2.0`
`prompt`	string	✅	Text description of the video
`duration`	integer	—	Video length in seconds
`resolution`	string	—	`480p` / `720p` / `1080p` / `1K` / `2K` / `4K`
`aspect_ratio`	string	—	`16:9` / `9:16` / `1:1` / `4:3` / `3:4` / `3:2` / `2:3` / `21:9` / `9:21`
`size`	string	—	Exact pixels `WIDTHxHEIGHT` (e.g. `1280x720`), an alternative to `resolution` + `aspect_ratio`
`frame_images`	array	—	Frame control (image-to-video / first-and-last frame). Present ⇒ treated as image-to-video. See below
`input_references`	array	—	Guide subject / style (reference-to-video), not precise frame anchors. See below
`real_person`	boolean	—	Default `false`. Set `true` to preprocess real-person reference images before generation; requires at least one image reference
`generate_audio`	boolean	—	Defaults to `true` on models that support audio output
`seed`	integer	—	Deterministic generation seed (not guaranteed on all providers)
`callback_url`	string	—	Terminal-state webhook URL, must be HTTPS (see Webhooks)
`provider`	object	—	`type` pins the serving provider, `options` passes provider-specific parameters through. See Provider routing

`frame_images[]` element

Each element pins one frame of the output. frame_type is first_frame or last_frame.


{
  "type": "image_url",
  "image_url": { "url": "https://example.com/first.jpg" },
  "frame_type": "first_frame"
}

`input_references[]` element

Pass image / audio / video references by type — these guide subject, style, and consistency, not precise frame anchors:


{ "type": "image_url", "image_url": { "url": "https://example.com/subject.jpg" } }
{ "type": "audio_url", "audio_url": { "url": "https://example.com/voice.mp3" } }
{ "type": "video_url", "video_url": { "url": "https://example.com/ref.mp4" } }

Media	`type`	Max count	Other constraints
Image	`image_url`	≤ 9	—
Audio	`audio_url`	≤ 3	≤ 15s per clip
Video	`video_url`	≤ 1	—

Exceeding any limit returns 400 too_many_references (see Errors).

frame_images and input_references are mutually exclusive — a single request uses one or the other, never both. Sending both returns 400 references_conflict.

`real_person`: Real-person reference images

For the one-step Ofox workflow, the comparison with Seedance asset enrollment, and practical retry guidance, see Real-person reference images.

Set the top-level real_person field to true when a reference image contains an identifiable real person. Ofox applies privacy-preserving preprocessing to every image in the selected reference field before submitting the generation request. The default is false, so existing requests are unchanged.


{
  "model": "bytedance/seedance-2.0",
  "prompt": "The person walks through a cinematic night market",
  "real_person": true,
  "input_references": [
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/person.jpg" }
    }
  ]
}

You can use real_person with images in either frame_images or input_references; those two fields remain mutually exclusive. At least one image reference is required, otherwise the API returns 400 invalid_request.

Preprocessing can reduce false rejections by upstream anti-deepfake checks, but it does not bypass the provider’s content policy or guarantee acceptance. The provider may still reject the request; a rejected job is not charged, and you can correct the input or retry. See real_person preprocessing errors for input errors you can fix directly.

Generation mode (implicit)

There is no gen_mode field. The mode is inferred from which inputs you send:

Mode	Detected when
`text2video`	Neither `frame_images` nor `input_references`
`img2video`	`frame_images` with one `first_frame`
`img2video_end`	`frame_images` with `first_frame` + `last_frame`
`imgref2video`	`input_references`, images only
`mixref2video`	`input_references` mixing image / audio / video

Response

202 Accepted — the task is accepted with status: "pending" and a polling_url:


{
  "id": "9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718",
  "status": "pending",
  "polling_url": "https://api.ofox.io/v1/videos/9bcf3c60-7db2-4e1a-a1b2-c3d4e5f60718"
}

Poll polling_url (or wait for a webhook) until the task reaches a terminal state — see Get video status.

Request examples

One /v1/videos schema covers every generation mode; the mode is chosen implicitly from your inputs. Each example below runs as-is.

Text to video

No frame_images / input_references → text-to-video.

Terminal


# Optional: pin a provider. Omit it and the platform routes for you
# "provider": { "type": "byteplus" }
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.5",
    "prompt": "A golden retriever running on the beach at sunset",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

Image to video

frame_images with one first_frame → animate from a starting image.

Terminal


# Optional: pin a provider. Omit it and the platform routes for you
# "provider": { "type": "byteplus" }
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "Make the dog in the frame start running",
    "duration": 5,
    "frame_images": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/dog.jpg" },
        "frame_type": "first_frame"
      }
    ]
  }'

First & last frame

frame_images with first_frame + last_frame → interpolate between two frames.

Terminal


# Optional: pin a provider. Omit it and the platform routes for you
# "provider": { "type": "byteplus" }
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "Smoothly transition between the two frames",
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/start.jpg" }, "frame_type": "first_frame" },
      { "type": "image_url", "image_url": { "url": "https://example.com/end.jpg" },   "frame_type": "last_frame" }
    ]
  }'

Image reference

input_references with images only (guides subject / style, not frame anchors) — up to 9.

Terminal


# Optional: pin a provider. Omit it and the platform routes for you
# "provider": { "type": "byteplus" }
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "This character skiing down a snowy mountain",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/character.jpg" } },
      { "type": "image_url", "image_url": { "url": "https://example.com/style-ref.jpg" } }
    ]
  }'

Mixed reference

input_references mixing image / audio / video (image ≤ 9 · audio ≤ 3, ≤ 15s each · video ≤ 1).

Terminal


# Optional: pin a provider. Omit it and the platform routes for you
# "provider": { "type": "byteplus" }
curl -X POST https://api.ofox.io/v1/videos \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bytedance/seedance-2.0",
    "prompt": "Have the character speak in the tone of this voice clip, in the style of this reference video",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/character.jpg" } },
      { "type": "audio_url", "audio_url": { "url": "https://example.com/voice.mp3" } },
      { "type": "video_url", "video_url": { "url": "https://example.com/style-ref.mp4" } }
    ]
  }'

Stackable options

The fields below are orthogonal to the generation mode — add any of them to any request body above.

Webhook (callback_url)

Receive a POST at your endpoint when the task reaches a terminal state instead of polling.


{
  "model": "bytedance/seedance-2.5",
  "prompt": "...",
  "callback_url": "https://your-app.example/webhooks/ofox-video"
}

callback_url must be HTTPS. See Webhooks for the payload and signature.

Pin a provider (provider.type)

Pass provider-specific parameters (e.g. watermark) through provider.options.<slug>.


{
  "model": "alibaba/wan-2.7",
  "prompt": "...",
  "provider": {
    "options": { "dashscope": { "watermark": false } }
  }
}

Exact pixel size

Use size for exact pixels in place of resolution + aspect_ratio.


{
  "model": "bytedance/seedance-2.5",
  "prompt": "...",
  "size": "1280x720"
}

Audio + seed

Use the top-level provider.type to pin the task to one provider — see Provider routing.

Create video

Request parameters

frame_images[] element

input_references[] element

real_person: Real-person reference images

Generation mode (implicit)

Response

Request examples

Text to video

Image to video

First & last frame

Image reference

Mixed reference

Stackable options

Webhook (callback_url)

Pin a provider (provider.type)

Exact pixel size

Audio + seed

`frame_images[]` element

`input_references[]` element

`real_person`: Real-person reference images