توليد الفيديو باستخدام 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

عنوان رد نداء أصلي اختياري. تعتمد الإتاحة على القناة المختارة؛ واستخدم GET https://api.apihop.ai/v1/jobs/{jobId} للنتيجة المعتمدة.

المحتوى متعدد الوسائط

قد تستخدم عناوين الوسائط عناوين HTTP(S) عامة أو معرفات 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 عنصر وسائط، عبر المحتوى المختصر ومحدد النوع. يتطلب الصوت صورة أو فيديو. استخدم prompt على المستوى الأعلى بدلا من محتوى type: "text". قدم اسما بديلا واحدا فقط لكل إعداد. ترفض الضوابط غير المدعومة. الحقول first_frame_url وlast_frame_url وreference_image_urls وreference_video_urls وreference_audio_urls على المستوى الأعلى اختصارات خاصة بالأدوار. لا تمرر الحقول غير المدرجة داخل عناصر المحتوى.

إعادة استخدام مهمة مسودة

draft_task حصرية لـSeedance 2.5. تعيد استخدام عينة قائمة متوافقة ومكتملة؛ ولا تحدد هذه الصفحة ضوابط إنشاء العينات.

يجب أن تتضمن metadata.content عنصر draft_task واحدا بالضبط.
فضل jobId العشري النصي من Synapse للعينة القائمة كقيمة draft_task.id. يقبل أيضا معرف منصة task_... قائم ومسجل؛ ولا تستخدم معرف مهمة المزود الخام أو تختلق معرفا.
يجب أن تتبع العينة الحساب نفسه وتستخدم النموذج وقناة المعالجة نفسيهما، وأن تكون مكتملة وأن يكون إنشاؤها قبل أقل من 7 أيام.
لا تقدم prompt أو مدخلات صور/فيديو/صوت أو duration أو ratio أو 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. يعني نجاح الإرسال قبول المهمة، وليس اكتمالها. استطلع GET https://api.apihop.ai/v1/jobs/{jobId} بمفتاح API من الحساب نفسه. راجع جلب مهمة غير متزامنة.

عندما تكون الحالة COMPLETED، اقرأ data.outputResult. اقبل قيم السلسلة النصية والمصفوفة معا لحقل url في كل كائن نتيجة.