توليد الفيديو باستخدام Seedance 2.0 | وثائق API

# Seedance 2.0 Video Generation

Seedance 2.0 text, first/last-frame, multimodal, and audio generation parameters.

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

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

## Authentication

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

## Body

### `model` (string, required)

`seedance-2.0` or its alias `seedance-2-0`.

### `prompt` (string)

Video prompt. Required for text-only generation; may be omitted or blank when image or video references are supplied. Audio alone is not a valid input. Text items inside `metadata.content` are discarded; only this top-level prompt is used.

### `seconds` (string, Default: 5)

Integer string from `"4"` through `"15"`. The numeric `duration` alias is also accepted. If both are supplied, they must agree. Automatic duration (`-1`) is not supported.

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

Output resolution: `480p`, `720p`, `1080p`, or `4k`. Not an aspect ratio. Resolution precedence: `metadata.resolution`, `size`, then `resolution`.

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

`16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`, or `adaptive`. `aspect_ratio` and `ratio` are aliases; `metadata.ratio` takes precedence. Use one alias for each setting.

### `metadata` (object)

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

### `images` (string[])

Image shorthand: the first image is the first frame and the second is the last frame. For precise roles, use `metadata.content`. Existing `imageUrls`, `imageUrl`, `image_urls`, and `image_url` aliases remain accepted with the same frame semantics.

### `imageWithRoles` (object[])

Images with `url` and `role`: `first_frame`, `last_frame`, or `reference_image`. `image_with_roles` is an alias. Both versions also accept typed `metadata.content`.

### `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 reference in the same request.

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

Each `metadata.content` media item contains its matching nested URL object. Media URLs may use public HTTP(S) URLs or existing `asset://` identifiers.

| Type | URL 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` |

Up to 9 images, 3 videos, and 3 audio files are accepted, including shorthand and typed content. Audio requires an image or video. `draft_task` is not supported. Use top-level `prompt` instead of `type: "text"` content items. 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.

Unsupported controls such as `negativePrompt`, `seed`, `returnLastFrame`, `nsfwCheck`, `tools`, `webhook`, `watermark`, `outputFormat`, and their snake-case aliases are rejected. `width`, `height`, `fps`, `cfgScale`, `steps`, and `style` are not supported.

## Request Examples

### Text-to-Video

```json
{
  "model": "seedance-2.0",
  "prompt": "A quiet city street at dawn, slow forward camera movement",
  "seconds": "5",
  "size": "720p",
  "metadata": {"ratio": "16:9", "generate_audio": true}
}
```

### First and Last Frames

```json
{
  "model": "seedance-2.0",
  "seconds": "5",
  "metadata": {
    "resolution": "720p",
    "ratio": "9:16",
    "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"}
    ]
  }
}
```

### Image and Audio References

```json
{
  "model": "seedance-2.0",
  "prompt": "Animate the scene to match the rhythm",
  "metadata": {
    "resolution": "720p",
    "generate_audio": true,
    "content": [
      {"type": "image_url", "image_url": {"url": "asset://existing-image-id"}, "role": "reference_image"},
      {"type": "audio_url", "audio_url": {"url": "https://example.com/beat.mp3"}, "role": "reference_audio"}
    ]
  }
}
```

## 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 a string `url` and an array of URLs in each result object. Charges depend on actual completion tokens and output resolution; video references select the video-input rate, while image/audio-only references do not.

أنشئ مهمة Seedance 2.0 غير متزامنة. بالنسبة إلى Seedance 2.5، استخدم مرجع معاملاته المستقل.

المصادقة

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

جسم الطلب

modelstringمطلوب

seedance-2.0 أو اسمه البديل seedance-2-0.

promptstring

تعليمة الفيديو. مطلوبة للتوليد من النص فقط؛ ويمكن حذفها أو تركها فارغة عند تقديم مراجع صور أو فيديو. الصوت وحده ليس مدخلا صالحا. تهمل العناصر النصية داخل metadata.content؛ ولا تستخدم إلا هذه التعليمة على المستوى الأعلى.

secondsstringالقيمة الافتراضية: 5

سلسلة عدد صحيح من "4" إلى "15". يقبل أيضا الاسم البديل الرقمي duration. إذا قدم كلاهما، فيجب أن يتفقا. لا تدعم المدة التلقائية (-1).

sizestringالقيمة الافتراضية: 720p

دقة الإخراج: 480p أو 720p أو 1080p أو 4k. وليست نسبة أبعاد. أولوية الدقة: metadata.resolution ثم size ثم resolution.

aspectRatiostringالقيمة الافتراضية: 16:9

16:9 أو 9:16 أو 1:1 أو 4:3 أو 3:4 أو 21:9 أو adaptive. يعد aspect_ratio وratio اسمين بديلين؛ وتكون الأولوية لـmetadata.ratio. استخدم اسما بديلا واحدا لكل إعداد.

metadataobject

يقبل resolution وratio وcontent وgenerate_audio. اضبط generate_audio على قيمة منطقية للتحكم في الصوت المولد. يعد generateAudio / generate_audio على المستوى الأعلى اسمين بديلين؛ قدم تحكما صوتيا واحدا فقط.

imagesstring[]

اختصار الصور: الصورة الأولى هي الإطار الأول والثانية هي الإطار الأخير. للأدوار الدقيقة، استخدم metadata.content. تظل الأسماء البديلة القائمة imageUrls وimageUrl وimage_urls وimage_url مقبولة بدلالات الإطارات نفسها.

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 أسماء بديلة. يتطلب مرجع صورة أو فيديو في الطلب نفسه.

callback_urlstring

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

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

يحتوي كل عنصر وسائط في metadata.content على كائن URL المتداخل المطابق له. قد تستخدم عناوين الوسائط عناوين HTTP(S) عامة أو معرفات asset:// قائمة.

النوع	حقل URL	الأدوار
`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`

تقبل حتى 9 صور و3 فيديوهات و3 ملفات صوتية، بما في ذلك المحتوى المختصر ومحدد النوع. يتطلب الصوت صورة أو فيديو. لا تدعم draft_task. استخدم prompt على المستوى الأعلى بدلا من عناصر المحتوى type: "text". الحقول first_frame_url وlast_frame_url وreference_image_urls وreference_video_urls وreference_audio_urls على المستوى الأعلى اختصارات خاصة بالأدوار. لا تمرر الحقول غير المدرجة داخل عناصر المحتوى.

ترفض عناصر التحكم غير المدعومة مثل negativePrompt وseed وreturnLastFrame وnsfwCheck وtools وwebhook وwatermark وoutputFormat وأسمائها البديلة بصيغة snake-case. لا تدعم width وheight وfps وcfgScale وsteps وstyle.

أمثلة الطلبات

تحويل النص إلى فيديو

json

{
  "model": "seedance-2.0",
  "prompt": "A quiet city street at dawn, slow forward camera movement",
  "seconds": "5",
  "size": "720p",
  "metadata": {"ratio": "16:9", "generate_audio": true}
}

الإطار الأول والأخير

json

{
  "model": "seedance-2.0",
  "seconds": "5",
  "metadata": {
    "resolution": "720p",
    "ratio": "9:16",
    "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"}
    ]
  }
}

مراجع الصور والصوت

json

{
  "model": "seedance-2.0",
  "prompt": "Animate the scene to match the rhythm",
  "metadata": {
    "resolution": "720p",
    "generate_audio": true,
    "content": [
      {"type": "image_url", "image_url": {"url": "asset://existing-image-id"}, "role": "reference_image"},
      {"type": "audio_url", "audio_url": {"url": "https://example.com/beat.mp3"}, "role": "reference_audio"}
    ]
  }
}

الإرسال والنتيجة

تتضمن data في الاستجابة الحقول jobId وstatus وmodel وmessage. يعني نجاح الإرسال قبول المهمة، وليس اكتمالها. استطلع GET https://api.apihop.ai/v1/jobs/{jobId} بمفتاح API من الحساب نفسه. راجع جلب مهمة غير متزامنة.

عندما تكون الحالة COMPLETED، اقرأ data.outputResult. اقبل url كسلسلة نصية أو مصفوفة عناوين في كل كائن نتيجة. تعتمد الرسوم على رموز الإكمال الفعلية ودقة الإخراج؛ وتختار مراجع الفيديو سعر مدخل الفيديو، بينما لا تختاره مراجع الصور/الصوت فقط.