Seedance 2.5 video oluşturma | API Belgeleri

# 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`.

Asenkron bir Seedance 2.5 işi oluşturun. Seedance 2.0 için ayrı parametre başvurusunu kullanın.

Kimlik doğrulama

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

İstek gövdesi

modelstringzorunlu

seedance-2.5.

promptstring

Video istemi. Yalnızca metinle üretimde zorunludur; görsel/video referansı varsa atlanabilir ya da boş bırakılabilir. draft_task yeniden kullanımında atlayın. metadata.content metin öğeleri atılır; üst düzey prompt belirleyicidir.

durationnumberVarsayılan: 5

4 ile 30 arasında tam sayı veya otomatik süre için -1. Yerel seconds eşdeğer tam sayı dizesini kabul eder. metadata.duration da kabul edilir. Sağlanan süre takma adları uyuşmalıdır. draft_task yeniden kullanımında tüm süre kontrollerini atlayın.

resolutionstringVarsayılan: 720p

480p, 720p veya 1080p. Yerel size çözünürlük belirtebilir; metadata.resolution önceliklidir. 4k desteklenmez.

aspectRatiostringVarsayılan: 16:9

16:9, 9:16, 1:1, 4:3, 3:4, 21:9 veya adaptive. aspect_ratio, ratio ve metadata.ratio kabul edilir. size içindeki mevcut oran değerleri uyumluluk için kabul edilmeye devam eder, ancak size içindeki çözünürlük değeri çözünürlük anlamına gelir. İlk/son kare girdisi adaptive gerektirir; açık oran olmadan kare rolleri varsa bu seçilir.

metadataobject

resolution, ratio, duration, content, generate_audio ve output_format kabul edilir. Oluşturulan ses için generate_audio değerini boolean yapın. Üst düzey generateAudio / generate_audio takma adlardır; tek ses kontrolü kullanın.

imageUrlsstring[]

Referans görseller. images, imageUrl, image_urls ve image_url takma adlardır. Yerel images kısa biçimi ilk iki görselini ilk/son kare olarak kullanır; imageUrls referans görsel anlamını korur.

imageWithRolesobject[]

url ve role içeren role dayalı görseller: first_frame, last_frame veya reference_image. image_with_roles bir takma addır. Tipli metadata.content da kabul edilir.

videoUrlsstring[]

Referans videolar. videoUrl, video_urls ve video_url takma adlardır.

audioUrlsstring[]

Referans ses. audioUrl, audio_urls ve audio_url takma adlardır. Aynı istekte görsel veya video gerekir.

outputFormatstringVarsayılan: mp4

Yalnızca mp4. output_format ve metadata.output_format kabul edilir. mov ve watermark desteklenmez.

callback_urlstring

İsteğe bağlı yerel geri çağrı URL’si. Kullanılabilirlik seçilen kanala bağlıdır; belirleyici sonuç olarak GET https://api.apihop.ai/v1/jobs/{jobId} kullanın.

Çok modlu içerik

Medya URL’leri herkese açık HTTP(S) URL’leri veya mevcut asset:// kimlikleri olabilir.

Tür	İç içe alan	Roller
`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`	Rol yok; yalnızca örnek yeniden kullanımı

Kısa biçimler ve tipli içerik toplamında en fazla 30 görsel, 10 video ve 10 ses dosyası; toplam en fazla 50 medya öğesi kabul edilir. Ses için görsel veya video gerekir. type: "text" içerik yerine üst düzey prompt kullanın. Her ayar için tek takma ad sağlayın. Desteklenmeyen kontroller reddedilir. Üst düzey first_frame_url, last_frame_url, reference_image_urls, reference_video_urls ve reference_audio_urls role özel kısa biçimlerdir. İçerik öğelerindeki listelenmemiş alanlar iletilmez.

Taslak görev yeniden kullanımı

draft_task yalnızca Seedance 2.5’e özgüdür. Mevcut uyumlu ve tamamlanmış örneği yeniden kullanır; bu sayfa örnek oluşturma kontrollerini tanımlamaz.

metadata.content tam olarak bir draft_task öğesi içermelidir.
draft_task.id için mevcut örneğin Synapse ondalık dize jobId değerini tercih edin. Kaydedilmiş mevcut platform task_... kimliği de kabul edilir; üst sağlayıcının ham görev kimliğini kullanmayın veya kimlik uydurmayın.
Örnek aynı hesaba ait olmalı, aynı modeli ve işleme kanalını kullanmalı, tamamlanmış olmalı ve 7 günden daha kısa süre önce oluşturulmuş olmalıdır.
İstem, görsel/video/ses girdileri, süre, oran, seed, generate_audio, çıktı biçimi veya omni_reference_task_type sağlamayın. Örneğin ayarları yeniden kullanılır.
Çıktı çözünürlüğü sağlanabilir.

Başvurulan görev başarıyla tamamlanmış olsa bile uyumluluk ve sahiplik kontrolleri yeniden kullanımı reddedebilir. Her normal üretimin yeniden kullanılabilir örnek olduğunu varsaymayın.

İstek örnekleri

Çok modlu referans

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"}
    ]
  }
}

İlk ve son kareler

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"}
    ]
  }
}

Mevcut örneği yeniden kullanma

EXISTING_SAMPLE_JOB_ID değerini gerçek uyumlu ve tamamlanmış örneğin döndürdüğü jobId ile değiştirin. Aşağıdaki yer tutucu çalışan bir görev kimliği değildir.

json

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

Gönderim ve sonuç

Yanıttaki data, jobId, status, model ve message içerir. Gönderimin başarılı olması işin kabul edildiği, tamamlandığı değil, anlamına gelir. Aynı hesabın API anahtarıyla GET https://api.apihop.ai/v1/jobs/{jobId} sorgulayın. Asenkron işi sorgulama bölümüne bakın.

Durum COMPLETED olduğunda data.outputResult okuyun. Her sonuç nesnesinin url alanında hem dize hem dizi değerlerini kabul edin.