# Seedance API: first/last frame, reference images, duration and resolution parameters, and errors

Source: https://ofox.io/docs/develop/models/seedance

ByteDance's video generation models, four in total, called through the OfoxAI video endpoint `POST /v1/videos`. Tasks run asynchronously: creating a task returns a task ID, which you then use to query the result.

## Choosing a model

**Key point**:Choose 2.0 when you need 4K output; choose 2.5 when you need 30-second duration or a 21:9 aspect ratio; choose Mini or Fast for batch generation of 480p and 720p videos.

| Model | Resolutions (default) | Duration | Aspect ratios |
|---|---|---|---|
| Seedance 2.5 | `480p` `720p` `1080p` (`720p`) | 4–30 s | `21:9` `16:9` `4:3` `1:1` `3:4` `9:16` `adaptive` |
| Seedance 2.0 | `480p` `720p` `1080p` `4k` (`1080p`) | 4–15 s | `16:9` `9:16` `1:1` `adaptive` |
| Seedance 2.0 Fast | `480p` `720p` (`720p`) | 4–15 s | Same as 2.0 |
| Seedance 2.0 Mini | `480p` `720p` (`720p`) | 4–15 s | Same as 2.0 |

All four support text-to-video, image-to-video, and video reference, and can generate a synchronized audio track (`generate_audio` defaults to `true`). `adaptive` keeps the input image's aspect ratio.

**Model IDs (copy them exactly)**

- Seedance 2.5: `bytedance/seedance-2.5` — 30 s, 21:9
- Seedance 2.0: `bytedance/seedance-2.0` — 4K
- Seedance 2.0 Fast: `bytedance/seedance-2.0-fast` — 480p, 720p
- Seedance 2.0 Mini: `bytedance/seedance-2.0-mini` — 480p, 720p

The table above matches the `video_attributes` returned by the [Models API](https://ofox.io/docs/api/openai/models); if model capabilities change, the API response takes precedence. Billing is per second, and the actual charge is `usage.video_cost` in the task result. For prices, see the [model page](https://ofox.io/models/bytedance/seedance-2.5).

**Pass `resolution` and `duration` explicitly.** If omitted, 2.0 defaults to `1080p`; cost is calculated by resolution tier and is higher than at `720p`.

## Examples

**Key point**:All five generation modes share one endpoint. The mode is determined by the input fields you send; no mode parameter is needed.

The examples below show only the request that creates the task. For the full flow of querying status and downloading the result after creation, see [Video API · Quickstart](https://ofox.io/docs/api/videos#quickstart).

**Text to video**

Send only `prompt`.

```bash filename="Terminal"
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-mini",
    "prompt": "A fox running through the snow, the camera following it",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'
```

**Image to video**

Pass one `first_frame` in `frame_images`; the video uses that image as its first frame. The aspect ratio can be set to `adaptive` to keep the image's ratio.

```bash filename="Terminal"
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": "The dog in the frame runs toward the camera",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "adaptive",
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/dog.jpg" }, "frame_type": "first_frame" }
    ]
  }'
```

**First & last frame**

Pass `first_frame` and `last_frame` in `frame_images` to generate the transition between the two frames. Sending only `last_frame` returns 400.

```bash filename="Terminal"
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": "A flower bud slowly opens into a rose in full bloom",
    "duration": 5,
    "resolution": "720p",
    "frame_images": [
      { "type": "image_url", "image_url": { "url": "https://example.com/bud.jpg" }, "frame_type": "first_frame" },
      { "type": "image_url", "image_url": { "url": "https://example.com/rose.jpg" }, "frame_type": "last_frame" }
    ]
  }'
```

**Image reference**

Pass images in `input_references` (up to 9) to keep a person, product, or style consistent; they are not used as fixed frames. Refer to each image in the prompt as "image 1", "image 2", and so on.

```bash filename="Terminal"
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": "The girl in image 1 holds the cup from image 2 and smiles by a café window",
    "duration": 5,
    "resolution": "720p",
    "input_references": [
      { "type": "image_url", "image_url": { "url": "https://example.com/girl.jpg" } },
      { "type": "image_url", "image_url": { "url": "https://example.com/cup.jpg" } }
    ]
  }'
```

**Audio/video reference**

`input_references` can mix images, audio (up to 3 clips, each no longer than 15 seconds), and video (up to 1 clip). When video is used as input, billed seconds may include the input video's duration.

```bash filename="Terminal"
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": "The character speaks in the tone of this voiceover, with camera style based on this video",
    "duration": 5,
    "resolution": "720p",
    "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" } }
    ]
  }'
```

- `frame_images` and `input_references` cannot be sent together; sending both returns `400 references_conflict`.
- Images can be public URLs or strings starting with `data:image/...;base64,`.
- Pass `"generate_audio": false` when you do not need an audio track.
- For the full field structure, see [Create video task](https://ofox.io/docs/api/videos/create).

## Real-person reference images

**Key point**:When calling through OfoxAI, you do not need to complete Seedance's asset library verification; just add `real_person: true` at the top level of the request.

ByteDance's official Seedance API does not allow direct upload of reference images or videos containing real human faces. The [official BytePlus Seedance 2.0 documentation](https://docs.byteplus.com/en/docs/modelark/1520757) requires authorized real-person portrait assets, and the [Volcano Engine Ark real-person portrait library guide](https://www.volcengine.com/docs/82379/2315856) lists steps such as sending an invitation, identity verification and authorization, uploading assets, and receiving authorization to obtain an asset ID.

| Step | Calling the official Seedance API directly | Calling through OfoxAI |
|---|---|---|
| Before the first request | Create an asset group, complete real-person verification and authorization, upload and validate assets, obtain an asset ID | No advance enrollment on the provider's platform |
| Passing reference images | Use an active authorized asset `asset://<asset_id>` | Pass an image URL or `data:` URI in `frame_images` or `input_references` |
| Request switch | Switch to the approved asset URI | Add `"real_person": true` at the top level of the request |

```json
{
  "model": "bytedance/seedance-2.0",
  "prompt": "The person in the frame walks through a cinematic night market",
  "duration": 5,
  "resolution": "720p",
  "real_person": true,
  "input_references": [
    { "type": "image_url", "image_url": { "url": "https://example.com/person.jpg" } }
  ]
}
```

- OfoxAI applies privacy preprocessing to reference images before submission. This can reduce false rejections by upstream anti-deepfake review, but cannot guarantee upstream acceptance; tasks rejected upstream are not charged.
- `real_person` is a processing instruction, not proof of authorization. Only submit images you are legally entitled and authorized to use.
- For how to adjust images that are still rejected and for preprocessing error codes, see [Real-person reference images](https://ofox.io/docs/api/videos/real-person).

## Pin a provider

**Key point**:Seedance is served by two providers with different moderation strictness; if none is specified, the gateway distributes requests by weight.

| Provider | Description | Content moderation |
|---|---|---|
| `volcengine` | Volcano Engine Ark, ByteDance's platform for mainland China | Standard moderation |
| `byteplus` | BytePlus, ByteDance's platform outside mainland China | Allows not-for-all-audiences (NSFW) content |

To pin a provider, add this at the top level of the request:

```json
"provider": { "type": "byteplus" }
```

To generate not-for-all-audiences content, you must explicitly specify `byteplus`. Otherwise the request may be routed to `volcengine` and rejected by content moderation. Once a provider is specified, the request will not switch automatically if that provider is unavailable.

An invalid `provider.type` value returns `400 invalid_provider_type`; a specified provider that does not serve the model returns `400 provider_type_unavailable`. For general details, see [Video provider routing](https://ofox.io/docs/api/videos/provider-routing).

## Common errors

**Key point**:Parameter validation errors are returned at creation time; no task is created and nothing is charged. The error message lists the allowed values.

| HTTP · code | Error message | Cause | Fix |
|---|---|---|---|
| 400 `unsupported_parameter` | `duration 3 out of range [4, 15]` | Duration outside the model's range | 4–15 s for the 2.0 series, 4–30 s for 2.5 |
| 400 `unsupported_parameter` | `resolution "1080p" not supported; allowed: [480p 720p]` | Fast and Mini do not support 1080p | Use `720p`, or switch to 2.0 / 2.5 |
| 400 `unsupported_parameter` | `resolution "4k" not supported; allowed: [480p 720p 1080p]` | Only 2.0 supports 4K | Switch to `bytedance/seedance-2.0` |
| 400 `unsupported_parameter` | `aspect_ratio "21:9" not supported; allowed: [16:9 9:16 1:1 adaptive]` | The 2.0 series does not support 21:9 | Switch to 2.5, or use a supported ratio |
| 400 `references_conflict` | `frame_images and input_references are mutually exclusive` | Both input fields were sent | Use only one of them; see [Examples](#examples) |
| 400 `invalid_request` | `frame_images: last_frame requires a first_frame` | Only the last frame was sent | Add a `first_frame` |
| 400 `too_many_references` | `input_references over limit: images 10/9, audios 0/3, videos 0/1` | Reference inputs exceed the limit | Up to 9 images, 3 audio clips, and 1 video |
| 400 `invalid_request` | `real_person requires at least one image reference` | `real_person` is enabled but no image was sent | Add an image, or remove `real_person` |
| 400 `invalid_request` | `cannot unmarshal string into Go struct field CreateVideoRequest.duration of type int` | `duration` was sent as a string, e.g. `"5s"` | Use an integer, e.g. `5` |
| 400 `invalid_callback_url` | `callback_url must be a public HTTPS URL` | The callback address is not HTTPS, or is an internal address | Use a public HTTPS address |
| 404 `model_not_found` | `model not found` | Model ID misspelled, e.g. `bytedance/seedance-2` | Copy the model ID from this page |
| 402 `insufficient_credits` | — | Balance is insufficient for the estimated cost (no task is created) | Top up and retry |

If a task is created successfully but fails during generation, the query result is `status: "failed"`, with the reason in the `error` field; a timeout corresponds to `error.code: "expired"`. For the full list of error codes, see [Video API error codes](https://ofox.io/docs/api/videos/errors).

## Official docs
- [BytePlus Seedance 2.0 video generation API](https://docs.byteplus.com/en/docs/modelark/1520757)
- [Volcano Engine Ark documentation center](https://www.volcengine.com/docs/82379)
- [OfoxAI · Create video task](https://ofox.io/docs/api/videos/create)

## FAQ

**How do I make a first/last-frame video with Seedance?**

Pass two images in frame_images, one with frame_type first_frame and one with last_frame. Sending only last_frame returns 400 last_frame requires a first_frame. frame_images cannot be sent together with input_references.

**Does Seedance 2.0 support 4K?**

Only bytedance/seedance-2.0 supports 4k. 2.5 goes up to 1080p, and Fast and Mini up to 720p. An unsupported resolution returns 400, and the error message lists the allowed values.

**What is the maximum length Seedance can generate?**

Seedance 2.5 generates 4 to 30 seconds per task; 2.0, 2.0 Fast, and 2.0 Mini generate 4 to 15 seconds. Values outside the range return 400 duration out of range.

**Does Seedance support 21:9?**

Only Seedance 2.5 supports 21:9. The 2.0 series supports only 16:9, 9:16, 1:1, and adaptive.

**What should I do if a Seedance reference image with a real person returns an error?**

Calling the official API directly requires identity verification in the asset library first. Through OfoxAI, add real_person: true at the top level of the request and pass the image directly; OfoxAI applies privacy preprocessing first. If the upstream still rejects it, you are not charged; adjust the image following the advice on the real-person reference images page and retry.

**How many reference images can Seedance take at once?**

input_references accepts up to 9 images, 3 audio clips (each no longer than 15 seconds), and 1 video. Exceeding this returns 400 too_many_references.

**How long is the Seedance video URL valid after generation?**

Prefer mirror_urls. If only unsigned_urls is returned, it is a temporary upstream address that may expire after 24 hours, so download and save it promptly.