مرجع API
Seedance نص إلى فيديو
استخدم نقطة نهاية تحويل النص إلى فيديو لإنشاء مهمة غير متزامنة.
01
نظرة عامة
استخدم نقطة نهاية تحويل النص إلى فيديو مع نموذج مدعوم. استخدم معرّف المهمة المُعاد لاسترداد حالتها، أو أدخل callback_url للتسليمات الموثقة أدناه.
البدء السريع
- أنشئ مفتاح API واضبطه كـ RUNAPI_API_KEY.
- اختر نموذجاً مدعوماً وأرسل طلب POST يطابق مخطط ذلك النموذج.
- احفظ معرّف المهمة المُعاد، ثم استطلع الحالة حتى تبلغ حالة نهائية أو تعالج عمليات الاستدعاء الموثقة أدناه.
نقطة النهاية
- عنوان URL الأساسي
https://runapi.ai- إصدار API
v1- المصادقة
Authorization: Bearer YOUR_API_TOKEN
02
النماذج المدعومة
افتح صفحة النموذج للاطلاع على التسعير الحالي وحدود المعدل وتفاصيل الاستخدام التجاري.
03
نص JSONمخطط الطلب
تعتمد الحقول والقيم المسموح بها على النموذج المحدد. عند التوفير، يستقبل callback_url عمليات تسليم المهمة الموثّقة أدناه.
seedance-1.5-pro11 حقل
aspect_ratiostring
اختياري
القيم المسموح بها:
1:1, 4:3, 3:4, 16:9, 9:16, 21:9
callback_urlstring
اختياري
duration_secondsinteger
مطلوب
نطاق:
4 - 12
enable_safety_checkerboolean
اختياري
generate_audioboolean
اختياري
lock_cameraboolean
اختياري
modelstring
اختياري
output_resolutionstring
اختياري
القيم المسموح بها:
480p, 720p, 1080p
promptstring
اختياري
seedinteger
اختياري
نطاق:
-1 - 2147483647
source_image_urlsarray
اختياري
حد العناصر:
2
seedance-2-mini13 حقل
aspect_ratiostring
اختياري
القيم المسموح بها:
1:1, 4:3, 3:4, 16:9, 9:16, 21:9, auto
callback_urlstring
اختياري
duration_secondsinteger
اختياري
القيمة الافتراضية:
5
نطاق: 4 - 15
first_frame_image_urlstring
اختياري
generate_audioboolean
اختياري
last_frame_image_urlstring
اختياري
modelstring
اختياري
output_resolutionstring
اختياري
القيم المسموح بها:
480p, 720p
promptstring
اختياري
reference_audio_urlsarray
اختياري
حد العناصر:
3
reference_image_urlsarray
اختياري
حد العناصر:
9
reference_video_urlsarray
اختياري
حد العناصر:
3
web_searchboolean
اختياري
seedance-2.014 حقل
aspect_ratiostring
اختياري
القيم المسموح بها:
1:1, 4:3, 3:4, 16:9, 9:16, 21:9, auto
callback_urlstring
اختياري
duration_secondsinteger
اختياري
القيمة الافتراضية:
5
نطاق: 4 - 15
enable_safety_checkerboolean
اختياري
first_frame_image_urlstring
اختياري
generate_audioboolean
اختياري
last_frame_image_urlstring
اختياري
modelstring
اختياري
output_resolutionstring
اختياري
القيم المسموح بها:
480p, 720p, 1080p, 4k
promptstring
اختياري
reference_audio_urlsarray
اختياري
حد العناصر:
3
reference_image_urlsarray
اختياري
حد العناصر:
9
reference_video_urlsarray
اختياري
حد العناصر:
3
web_searchboolean
اختياري
seedance-2.0-fast14 حقل
aspect_ratiostring
اختياري
القيم المسموح بها:
1:1, 4:3, 3:4, 16:9, 9:16, 21:9, auto
callback_urlstring
اختياري
duration_secondsinteger
اختياري
القيمة الافتراضية:
5
نطاق: 4 - 15
enable_safety_checkerboolean
اختياري
first_frame_image_urlstring
اختياري
generate_audioboolean
اختياري
last_frame_image_urlstring
اختياري
modelstring
اختياري
output_resolutionstring
اختياري
القيم المسموح بها:
480p, 720p
promptstring
اختياري
reference_audio_urlsarray
اختياري
حد العناصر:
3
reference_image_urlsarray
اختياري
حد العناصر:
9
reference_video_urlsarray
اختياري
حد العناصر:
3
web_searchboolean
اختياري
seedance-2.516 حقل
aspect_ratiostring
اختياري
نسبة أبعاد المخرجات؛ يختارها RunAPI تلقائيًا عند تعيينها على auto.
القيم المسموح بها:1:1, 4:3, 3:4, 16:9, 9:16, 21:9, auto
القيمة الافتراضية: auto
callback_urlstring
اختياري
رابط Webhook لتحديثات المهام غير المتزامنة.
duration_secondsinteger
اختياري
مدة الفيديو بالثواني؛ تختار القيمة -1 المدة تلقائياً.
القيم المسموح بها:-1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30
القيمة الافتراضية: 5
enable_safety_checkerboolean
اختياري
ما إذا كان RunAPI يفحص المحتوى المُنتج للتحقق من السلامة.
first_frame_image_urlstring
اختياري
عنوان URL عام لصورة الإطار الأول لتوليد مُوجَّه بالإطارات.
generate_audioboolean
اختياري
ما إذا كان سيتم توليد صوت متزامن.
القيمة الافتراضية:true
last_frame_image_urlstring
اختياري
عنوان URL عام لصورة الإطار الأخير؛ يتطلب first_frame_image_url.
modelstring
مطلوب
معرّف نموذج RunAPI.
output_formatstring
اختياري
تنسيق حاوية الفيديو في الإخراج.
القيم المسموح بها:mp4, mov
القيمة الافتراضية: mp4
output_resolutionstring
اختياري
دقة فيديو الإخراج.
القيم المسموح بها:480p, 720p, 1080p
القيمة الافتراضية: 720p
promptstring
مطلوب
موجّه توليد الفيديو.
نطاق:3 - 30000
reference_audio_urlsarray
اختياري
عناوين URL عامة لملفات صوتية مرجعية؛ ما يصل إلى 10 ملفات صوتية.
حد العناصر:10
reference_image_urlsarray
اختياري
عناوين URL عامة لصور مرجعية؛ ما يصل إلى 30 صورة.
حد العناصر:30
reference_video_urlsarray
اختياري
عناوين URL عامة لمقاطع فيديو مرجعية؛ ما يصل إلى 10 مقاطع.
حد العناصر:10
return_last_frameboolean
اختياري
ما إذا كان سيتم إرجاع الإطار الأخير من الفيديو المُنتج.
القيمة الافتراضية:false
web_searchboolean
اختياري
ما إذا كان سيتم إثراء الموجّه بالبحث على الويب.
seedance-v1-pro10 حقل
aspect_ratiostring
اختياري
القيم المسموح بها:
1:1, 4:3, 3:4, 16:9, 9:16, 21:9
callback_urlstring
اختياري
duration_secondsinteger
مطلوب
القيم المسموح بها:
5, 10
enable_safety_checkerboolean
اختياري
first_frame_image_urlstring
اختياري
lock_cameraboolean
اختياري
modelstring
اختياري
output_resolutionstring
اختياري
القيم المسموح بها:
480p, 720p, 1080p
promptstring
اختياري
seedinteger
اختياري
seedance-v1-pro-fast8 حقل
callback_urlstring
اختياري
duration_secondsinteger
مطلوب
القيم المسموح بها:
5, 10
enable_safety_checkerboolean
اختياري
first_frame_image_urlstring
مطلوب
modelstring
اختياري
output_resolutionstring
اختياري
القيم المسموح بها:
720p, 1080p
promptstring
اختياري
seedinteger
اختياري
نطاق:
-1 - 2147483647
القواعد الشرطية
تسري هذه المتطلبات عندما تتطابق جميع الشروط المدرجة.
-
عندما
first_frame_image_url = {"present" => true},model = seedance-2.5- مطلوب
- غير مقبول
reference_image_urls,reference_video_urls,reference_audio_urls
-
عندما
last_frame_image_url = {"present" => true},model = seedance-2.5- مطلوب
first_frame_image_url- غير مقبول
reference_image_urls,reference_video_urls,reference_audio_urls
-
عندما
model = seedance-1.5-pro- مطلوب
- غير مقبول
first_frame_image_url,last_frame_image_url,reference_image_urls,reference_video_urls,reference_audio_urls,web_search,return_last_frame,output_format
-
عندما
model = seedance-2-mini- مطلوب
- غير مقبول
source_image_urls,lock_camera,seed,enable_safety_checker,return_last_frame,output_format
-
عندما
model = seedance-2.0- مطلوب
- غير مقبول
source_image_urls,lock_camera,seed,return_last_frame,output_format
-
عندما
model = seedance-2.0-fast- مطلوب
- غير مقبول
source_image_urls,lock_camera,seed,return_last_frame,output_format
-
عندما
model = seedance-2.5- مطلوب
- غير مقبول
source_image_urls,lock_camera,seed
-
عندما
model = seedance-v1-pro- مطلوب
- غير مقبول
source_image_urls,last_frame_image_url,reference_image_urls,reference_video_urls,reference_audio_urls,web_search,generate_audio,return_last_frame,output_format
-
عندما
model = seedance-v1-pro-fast- مطلوب
- غير مقبول
aspect_ratio,source_image_urls,lock_camera,last_frame_image_url,reference_image_urls,reference_video_urls,reference_audio_urls,web_search,generate_audio,return_last_frame,output_format
04
HTTP 202إنشاء قبول
POST /api/v1/seedance/text_to_video
مخطط الاستجابة
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}05
HTTP 200الاستطلاع قيد المعالجة
GET /api/v1/seedance/text_to_video/:id
مخطط الاستجابة
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}06
HTTP 200اكتمل الاستطلاع
GET /api/v1/seedance/text_to_video/:id
مخطط الاستجابة
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"last_frame_image_url": {
"type": "string",
"x-runapi-generated-media": true
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}07
HTTP 200فشل الاستطلاع
GET /api/v1/seedance/text_to_video/:id
مخطط الاستجابة
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}08
HTTP 200استدعاء العميل: مكتمل
POST callback_url
مخطط الاستجابة
JSON
{
"properties": {
"id": {
"type": "string"
},
"last_frame_image_url": {
"type": "string",
"x-runapi-generated-media": true
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}09
HTTP 200استدعاء العميل: فشل
POST callback_url
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"limit_cents": {
"type": "integer"
},
"message": {
"type": "string"
},
"reset_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"used_cents": {
"type": "integer"
},
"window": {
"enum": [
"1h",
"1d",
"7d",
"daily",
"weekly",
"monthly",
"lifetime"
],
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}10
HTTP 401الأخطاء
POST /api/v1/seedance/text_to_video
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Authentication required"
}11
HTTP 401الأخطاء
GET /api/v1/seedance/text_to_video/:id
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Authentication required"
}12
HTTP 400الأخطاء
POST /api/v1/seedance/text_to_video
مخطط الاستجابة
JSON
{
"oneOf": [
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "ملخص التحقق القابل للقراءة البشرية.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "رسائل التحقق مفتاحها حقل الطلب العام، مع مصفوفة من السلاسل القابلة للقراءة البشرية لكل حقل.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}مثال على الاستجابة
JSON
{
"error": "model must be one of: seedance-1.5-pro, seedance-2-mini, seedance-2.0, seedance-2.0-fast, seedance-2.5, seedance-v1-pro, seedance-v1-pro-fast"
}13
HTTP 402الأخطاء
POST /api/v1/seedance/text_to_video
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Insufficient balance"
}14
HTTP 429الأخطاء
POST /api/v1/seedance/text_to_video
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "API key credit limit exceeded"
}15
HTTP 409الأخطاء
POST /api/v1/seedance/text_to_video
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "The request uses features that are not supported for the selected model"
}16
HTTP 429الأخطاء
POST /api/v1/seedance/text_to_video
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Rate limit reached. Please retry later."
}17
HTTP 503الأخطاء
POST /api/v1/seedance/text_to_video
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Service under maintenance, please try again later"
}18
HTTP 504الأخطاء
POST /api/v1/seedance/text_to_video
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "The request timed out"
}19
HTTP 404الأخطاء
GET /api/v1/seedance/text_to_video/:id
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Task with id 'tsk_reference_demo' not found"
}20
نماذج الأكواد المولَّدة
استخدم cURL مباشرةً، أو ثبّت SDK للغة البرمجة التي تستخدمها. كل نموذج يُرسل الطلب الذي تم التحقق من صحته كما هو موضح في هذا المرجع.
التثبيت
Shell
pip install runapi-seedance
PYTHON
import os
from runapi.seedance import SeedanceClient
client = SeedanceClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.text_to_video.create(
model="seedance-1.5-pro",
duration_seconds=5,
prompt="A time-lapse of clouds moving over a mountain lake."
)