Seedance 2.5 동영상 생성 | API 문서

# Seedance 2.5 Video Generation

Seedance 2.5 multimodal content, generated audio, and draft-task reuse parameters.

POST https://api.apihop.ai/v1/video/seedance

Create an asynchronous Seedance 2.5 job. For Seedance 2.0, use its [separate parameter reference](https://apihop.ai/en/docs/api-reference/BytePlus/seedance-2-0).

## Authentication

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Body

### `model` (string, required)

`seedance-2.5`.

### `prompt` (string)

Video prompt. Required for text-only generation; may be omitted or blank when image/video references are supplied. Omit it for `draft_task` reuse. `metadata.content` text items are discarded; top-level `prompt` is authoritative.

### `duration` (number, Default: 5)

Integer from `4` through `30`, or `-1` for automatic duration. Native `seconds` accepts the equivalent integer string. `metadata.duration` is also accepted. Supplied duration aliases must agree. Omit all duration controls for `draft_task` reuse.

### `resolution` (string, Default: 720p)

`480p`, `720p`, or `1080p`. Native `size` may specify resolution; `metadata.resolution` has precedence. `4k` is not supported.

### `aspectRatio` (string, Default: 16:9)

`16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, or `adaptive`. `aspect_ratio`, `ratio`, and `metadata.ratio` are accepted. Existing ratio values in `size` remain accepted for compatibility, but a resolution value in `size` means resolution. First/last-frame input requires `adaptive`; it is selected when frame roles are present without an explicit ratio.

### `metadata` (object)

Accepts `resolution`, `ratio`, `duration`, `content`, `generate_audio`, and `output_format`. Set `generate_audio` to a boolean for generated audio. Top-level `generateAudio` / `generate_audio` are aliases; use only one audio control.

### `imageUrls` (string[])

Reference images. `images`, `imageUrl`, `image_urls`, and `image_url` are aliases. Native `images` shorthand uses its first two images as first/last frames; `imageUrls` retains reference-image semantics.

### `imageWithRoles` (object[])

Role-based images with `url` and `role`: `first_frame`, `last_frame`, or `reference_image`. `image_with_roles` is an alias. Typed `metadata.content` is also accepted.

### `videoUrls` (string[])

Reference videos. `videoUrl`, `video_urls`, and `video_url` are aliases.

### `audioUrls` (string[])

Reference audio. `audioUrl`, `audio_urls`, and `audio_url` are aliases. Requires an image or video in the same request.

### `outputFormat` (string, Default: mp4)

`mp4` only. `output_format` and `metadata.output_format` are accepted. `mov` and `watermark` are not supported.

### `callback_url` (string)

Optional native callback URL. Availability depends on the selected channel; use `GET https://api.apihop.ai/v1/jobs/{jobId}` as the authoritative result.

## Multimodal Content

Media URLs may use public HTTP(S) URLs or existing `asset://` identifiers.

| Type | Nested field | Roles |
| --- | --- | --- |
| `image_url` | `image_url.url` | `first_frame`, `last_frame`, `reference_image` |
| `video_url` | `video_url.url` | `reference_video` |
| `audio_url` | `audio_url.url` | `reference_audio` |
| `draft_task` | `draft_task.id` | No role; sample reuse only |

Up to 30 images, 10 videos, and 10 audio files, with at most 50 media items total, are accepted across shorthand and typed content. Audio requires an image or video. Use top-level `prompt` instead of `type: "text"` content. Supply only one alias for each setting. Unsupported controls are rejected. Top-level `first_frame_url`, `last_frame_url`, `reference_image_urls`, `reference_video_urls`, and `reference_audio_urls` are role-specific shorthand. Unlisted fields inside content items are not forwarded.

## Draft-Task Reuse

`draft_task` is exclusive to Seedance 2.5. It reuses an existing compatible completed sample; this page does not define sample-creation controls.

- `metadata.content` must contain exactly one `draft_task` item.
- Prefer the existing sample's Synapse decimal-string `jobId` as `draft_task.id`.

An existing recorded platform `task_...` identifier is also accepted; do not use an upstream raw task ID or invent an identifier.

- The sample must belong to the same account, use the same model and processing

channel, be completed, and have been created less than 7 days ago.

- Do not supply prompt, image/video/audio inputs, duration, ratio, seed,

`generate_audio`, output format, or `omni_reference_task_type`. The sample's settings are reused.

- Output resolution may be supplied.

The compatibility and ownership checks may reject reuse even when the referenced task completed successfully. Do not assume every normal generation is a reusable sample.

## Request Examples

### Multimodal Reference

```json
{
  "model": "seedance-2.5",
  "prompt": "Keep the referenced character and camera movement in a coherent film",
  "seconds": "8",
  "size": "720p",
  "metadata": {
    "ratio": "16:9",
    "generate_audio": true,
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/camera.mp4"}, "role": "reference_video"},
      {"type": "audio_url", "audio_url": {"url": "https://example.com/music.mp3"}, "role": "reference_audio"}
    ]
  }
}
```

### First and Last Frames

```json
{
  "model": "seedance-2.5",
  "duration": 5,
  "metadata": {
    "ratio": "adaptive",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
      {"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"}, "role": "last_frame"}
    ]
  }
}
```

### Reuse an Existing Sample

Replace `EXISTING_SAMPLE_JOB_ID` with the actual compatible completed sample's returned `jobId`. The placeholder below is not a working task identifier.

```json
{
  "model": "seedance-2.5",
  "metadata": {
    "resolution": "1080p",
    "content": [
      {"type": "draft_task", "draft_task": {"id": "EXISTING_SAMPLE_JOB_ID"}}
    ]
  }
}
```

## Submission and Result

Response `data` contains `jobId`, `status`, `model`, and `message`. Submission success means the job was accepted, not completed. Poll `GET https://api.apihop.ai/v1/jobs/{jobId}` with the same account's API Key. See [Get Async Job](https://apihop.ai/en/docs/api-reference/jobs).

When status is `COMPLETED`, read `data.outputResult`. Accept both string and array values for each result object's `url`.

비동기 Seedance 2.5 작업을 생성합니다. Seedance 2.0은 별도 매개변수 참조를 사용하세요.

인증

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

요청 본문

modelstring필수

seedance-2.5입니다.

promptstring

동영상 프롬프트입니다. 텍스트만으로 생성할 때 필수이며 이미지/동영상 참조가 있으면 생략하거나 비워 둘 수 있습니다. draft_task 재사용 시 생략하세요. metadata.content의 텍스트 항목은 버리며 최상위 prompt가 기준입니다.

durationnumber기본값: 5

4부터 30까지의 정수 또는 자동 길이를 뜻하는 -1입니다. 기본 seconds는 동일한 정수 문자열을 허용합니다. metadata.duration도 허용합니다. 제공한 길이 별칭은 일치해야 합니다. draft_task 재사용 시 모든 길이 제어를 생략하세요.

resolutionstring기본값: 720p

480p, 720p 또는 1080p입니다. 기본 size로 해상도를 지정할 수 있으며 metadata.resolution이 우선합니다. 4k는 지원하지 않습니다.

aspectRatiostring기본값: 16:9

16:9, 9:16, 1:1, 4:3, 3:4, 21:9 또는 adaptive입니다. aspect_ratio, ratio, metadata.ratio를 허용합니다. 호환성을 위해 기존 size의 비율 값도 허용하지만 size의 해상도 값은 해상도를 의미합니다. 첫/마지막 프레임 입력에는 adaptive가 필요하며 프레임 역할이 있고 명시적 비율이 없으면 이를 선택합니다.

metadataobject

resolution, ratio, duration, content, generate_audio, output_format을 허용합니다. 생성 오디오는 generate_audio를 불리언으로 설정하세요. 최상위 generateAudio / generate_audio는 별칭이며 오디오 제어 하나만 사용하세요.

imageUrlsstring[]

참조 이미지입니다. images, imageUrl, image_urls, image_url은 별칭입니다. 기본 축약형 images는 앞의 두 이미지를 첫/마지막 프레임으로 사용하며 imageUrls는 참조 이미지 의미를 유지합니다.

imageWithRolesobject[]

url과 role이 있는 역할 기반 이미지입니다. 역할은 first_frame, last_frame 또는 reference_image이며 image_with_roles는 별칭입니다. 타입이 지정된 metadata.content도 허용합니다.

videoUrlsstring[]

참조 동영상입니다. videoUrl, video_urls, video_url은 별칭입니다.

audioUrlsstring[]

참조 오디오입니다. audioUrl, audio_urls, audio_url은 별칭입니다. 같은 요청에 이미지 또는 동영상이 필요합니다.

outputFormatstring기본값: mp4

mp4만 허용합니다. output_format과 metadata.output_format을 허용하며 mov와 watermark는 지원하지 않습니다.

callback_urlstring

선택적 기본 콜백 URL입니다. 가용성은 선택한 채널에 따라 달라지며 최종 결과는 GET https://api.apihop.ai/v1/jobs/{jobId}를 기준으로 하세요.

멀티모달 콘텐츠

미디어 URL은 공개 HTTP(S) URL 또는 기존 asset:// 식별자를 사용할 수 있습니다.

유형	중첩 필드	역할
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`
`video_url`	`video_url.url`	`reference_video`
`audio_url`	`audio_url.url`	`reference_audio`
`draft_task`	`draft_task.id`	역할 없음, 샘플 재사용 전용

축약형과 타입이 지정된 콘텐츠를 합쳐 이미지 최대 30개, 동영상 10개, 오디오 파일 10개를 허용하며 전체 미디어 항목은 최대 50개입니다. 오디오는 이미지 또는 동영상이 필요합니다. type: "text" 콘텐츠 대신 최상위 prompt를 사용하세요. 설정마다 별칭 하나만 제공하세요. 지원되지 않는 제어는 거부합니다. 최상위 first_frame_url, last_frame_url, reference_image_urls, reference_video_urls, reference_audio_urls는 역할별 축약형입니다. 콘텐츠 항목의 명시되지 않은 필드는 전달하지 않습니다.

초안 작업 재사용

draft_task는 Seedance 2.5 전용입니다. 기존의 호환되고 완료된 샘플을 재사용하며 이 페이지는 샘플 생성 제어를 정의하지 않습니다.

metadata.content에는 정확히 하나의 draft_task 항목이 있어야 합니다.
기존 샘플의 Synapse 십진수 문자열 jobId를 draft_task.id로 우선 사용하세요. 이미 기록된 플랫폼 task_... 식별자도 허용하지만 상위 공급자의 원시 작업 ID나 임의로 만든 식별자는 사용하지 마세요.
샘플은 같은 계정에 속하고 같은 모델 및 처리 채널을 사용하며 완료되어야 하고 생성 후 7일 미만이어야 합니다.
프롬프트, 이미지/동영상/오디오 입력, 길이, 비율, seed, generate_audio, 출력 형식 또는 omni_reference_task_type을 제공하지 마세요. 샘플 설정을 재사용합니다.
출력 해상도는 제공할 수 있습니다.

참조 작업이 성공적으로 완료되었어도 호환성과 소유권 검사에서 재사용을 거부할 수 있습니다. 모든 일반 생성 결과가 재사용 가능한 샘플이라고 가정하지 마세요.

요청 예제

멀티모달 참조

json

{
  "model": "seedance-2.5",
  "prompt": "Keep the referenced character and camera movement in a coherent film",
  "seconds": "8",
  "size": "720p",
  "metadata": {
    "ratio": "16:9",
    "generate_audio": true,
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/camera.mp4"}, "role": "reference_video"},
      {"type": "audio_url", "audio_url": {"url": "https://example.com/music.mp3"}, "role": "reference_audio"}
    ]
  }
}

첫 프레임과 마지막 프레임

json

{
  "model": "seedance-2.5",
  "duration": 5,
  "metadata": {
    "ratio": "adaptive",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/first.jpg"}, "role": "first_frame"},
      {"type": "image_url", "image_url": {"url": "https://example.com/last.jpg"}, "role": "last_frame"}
    ]
  }
}

기존 샘플 재사용

EXISTING_SAMPLE_JOB_ID를 실제 호환되고 완료된 샘플에서 반환한 jobId로 바꾸세요. 아래 자리표시자는 작동하는 작업 식별자가 아닙니다.

json

{
  "model": "seedance-2.5",
  "metadata": {
    "resolution": "1080p",
    "content": [
      {"type": "draft_task", "draft_task": {"id": "EXISTING_SAMPLE_JOB_ID"}}
    ]
  }
}

제출 및 결과

응답의 data에는 jobId, status, model, message가 포함됩니다. 제출 성공은 작업 수락을 의미하며 완료를 의미하지 않습니다. 같은 계정의 API 키로 GET https://api.apihop.ai/v1/jobs/{jobId}를 폴링하세요. 비동기 작업 조회를 참조하세요.

상태가 COMPLETED이면 data.outputResult를 읽으세요. 각 결과 객체의 url에는 문자열과 배열 값을 모두 허용하세요.