مرجع API
Kling صورة إلى فيديو
استخدم نقطة نهاية الصورة إلى فيديو لإنشاء مهمة غير متزامنة.
01
نظرة عامة
استخدم نقطة نهاية الصورة إلى فيديو مع نموذج مدعوم. استخدم معرّف المهمة المُعاد لاسترداد حالتها، أو أدخل callback_url للتسليمات الموثقة أدناه.
البدء السريع
- أنشئ مفتاح API واضبطه كـ RUNAPI_API_KEY.
- اختر نموذجاً مدعوماً وأرسل طلب POST يطابق مخطط ذلك النموذج.
- احفظ معرّف المهمة المُعاد، ثم استطلع الحالة حتى تبلغ حالة نهائية أو تعالج عمليات الاستدعاء الموثقة أدناه.
نقطة النهاية
- عنوان URL الأساسي
https://runapi.ai- إصدار API
v1- المصادقة
Authorization: Bearer YOUR_API_TOKEN
02
النماذج المدعومة
افتح صفحة النموذج للاطلاع على التسعير الحالي وحدود المعدل وتفاصيل الاستخدام التجاري.
03
نص JSONمخطط الطلب
تعتمد الحقول والقيم المسموح بها على النموذج المحدد. عند التوفير، يستقبل callback_url عمليات تسليم المهمة الموثّقة أدناه.
kling-o113 حقل
aspect_ratiostring
اختياري
نسبة أبعاد المخرجات.
القيم المسموح بها:16:9, 9:16, 1:1
القيمة الافتراضية: 16:9
callback_urlstring
اختياري
رابط Webhook لإشعارات غير متزامنة.
duration_secondsinteger
اختياري
المدة بالثواني.
القيم المسموح بها:5
القيمة الافتراضية: 5
enable_soundboolean
اختياري
يجب أن يظل توليد الصوت معطَّلاً.
القيمة الافتراضية:false
first_frame_image_urlstring
مطلوب
عنوان URL عام عبر HTTP(S) لصورة الإطار الأول بصيغة JPG أو JPEG أو PNG.
last_frame_image_urlstring
اختياري
عنوان URL عام عبر HTTP(S) لصورة الإطار الأخير بصيغة JPG أو JPEG أو PNG؛ لا يمكن دمجه مع reference_image_urls أو reference_video_url.
modestring
اختياري
وضع التوليد.
القيم المسموح بها:std, pro
القيمة الافتراضية: std
modelstring
مطلوب
معرّف النموذج.
preserve_reference_video_audioboolean
اختياري
الاحتفاظ بالصوت الأصلي لمقطع الفيديو المرجعي.
القيمة الافتراضية:false
promptstring
مطلوب
وصف الفيديو؛ أشر إلى الوسائط المرجعية بعلامات مرقّمة مطابقة.
نطاق:1 - 2500
reference_image_urlsarray
اختياري
عناوين URL مرتَّبة لصور مرجعية بتنسيق JPG أو JPEG أو PNG عبر HTTP(S) العام؛ لا يمكن دمجها مع last_frame_image_url.
نطاق العناصر:1 - 7
reference_video_typestring
اختياري
استخدم الفيديو كتحرير أساسي أو مرجع للميزات.
القيم المسموح بها:base, feature
القيمة الافتراضية: base
reference_video_urlstring
اختياري
عنوان URL عام عبر HTTP(S) لمقطع فيديو مرجعي بصيغة MP4 أو MOV؛ لا يمكن دمجه مع last_frame_image_url.
kling-v2.1-master-image-to-video9 حقل
aspect_ratiostring
اختياري
نسبة أبعاد المخرجات.
callback_urlstring
اختياري
رابط Webhook لإشعارات غير متزامنة.
cfg_scalenumber
اختياري
مقياس التوجيه (0-1).
duration_secondsinteger
اختياري
المدة بالثواني.
القيم المسموح بها:5, 10
first_frame_image_urlstring
مطلوب
عنوان URL لصورة الإطار الأول.
last_frame_image_urlstring
اختياري
عنوان URL لصورة الإطار الأخير للنماذج المدعومة من صورة إلى فيديو.
modelstring
مطلوب
معرّف النموذج.
negative_promptstring
اختياري
الموجّه السلبي.
promptstring
مطلوب
وصف الفيديو.
kling-v2.1-pro9 حقل
aspect_ratiostring
اختياري
نسبة أبعاد المخرجات.
callback_urlstring
اختياري
رابط Webhook لإشعارات غير متزامنة.
cfg_scalenumber
اختياري
مقياس التوجيه (0-1).
duration_secondsinteger
اختياري
المدة بالثواني.
القيم المسموح بها:5, 10
first_frame_image_urlstring
مطلوب
عنوان URL لصورة الإطار الأول.
last_frame_image_urlstring
اختياري
عنوان URL لصورة الإطار الأخير للنماذج المدعومة من صورة إلى فيديو.
modelstring
مطلوب
معرّف النموذج.
negative_promptstring
اختياري
الموجّه السلبي.
promptstring
مطلوب
وصف الفيديو.
kling-v2.1-standard9 حقل
aspect_ratiostring
اختياري
نسبة أبعاد المخرجات.
callback_urlstring
اختياري
رابط Webhook لإشعارات غير متزامنة.
cfg_scalenumber
اختياري
مقياس التوجيه (0-1).
duration_secondsinteger
اختياري
المدة بالثواني.
القيم المسموح بها:5, 10
first_frame_image_urlstring
مطلوب
عنوان URL لصورة الإطار الأول.
last_frame_image_urlstring
اختياري
عنوان URL لصورة الإطار الأخير للنماذج المدعومة من صورة إلى فيديو.
modelstring
مطلوب
معرّف النموذج.
negative_promptstring
اختياري
الموجّه السلبي.
promptstring
مطلوب
وصف الفيديو.
kling-v2.5-turbo-image-to-video-pro9 حقل
aspect_ratiostring
اختياري
نسبة أبعاد المخرجات.
callback_urlstring
اختياري
رابط Webhook لإشعارات غير متزامنة.
cfg_scalenumber
اختياري
مقياس التوجيه (0-1).
duration_secondsinteger
اختياري
المدة بالثواني.
القيم المسموح بها:5, 10
first_frame_image_urlstring
مطلوب
عنوان URL لصورة الإطار الأول.
last_frame_image_urlstring
اختياري
عنوان URL لصورة الإطار الأخير للنماذج المدعومة من صورة إلى فيديو.
modelstring
مطلوب
معرّف النموذج.
negative_promptstring
اختياري
الموجّه السلبي.
promptstring
مطلوب
وصف الفيديو.
kling-v2.69 حقل
aspect_ratiostring
اختياري
نسبة أبعاد المخرجات.
القيم المسموح بها:16:9, 9:16, 1:1
القيمة الافتراضية: 16:9
callback_urlstring
اختياري
رابط Webhook لإشعارات غير متزامنة.
duration_secondsinteger
اختياري
المدة بالثواني.
القيم المسموح بها:5, 10
القيمة الافتراضية: 5
enable_soundboolean
اختياري
تفعيل توليد الصوت؛ يتطلب وضع pro.
القيمة الافتراضية:false
first_frame_image_urlstring
مطلوب
عنوان URL لصورة الإطار الأول.
last_frame_image_urlstring
اختياري
عنوان URL لصورة الإطار الأخير؛ يتطلب وضع pro ومدة 5 ثوانٍ.
modestring
اختياري
وضع التوليد.
القيم المسموح بها:std, pro
القيمة الافتراضية: std
modelstring
مطلوب
معرّف النموذج.
promptstring
مطلوب
وصف الفيديو.
نطاق:1 - 2500
kling-v3-omni9 حقل
aspect_ratiostring
اختياري
نسبة أبعاد المخرجات.
القيم المسموح بها:16:9, 9:16, 1:1
القيمة الافتراضية: 16:9
callback_urlstring
اختياري
رابط Webhook لإشعارات غير متزامنة.
duration_secondsinteger
اختياري
المدة بالثواني.
القيم المسموح بها:3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
القيمة الافتراضية: 5
enable_soundboolean
اختياري
تفعيل توليد الصوت المتزامن.
القيمة الافتراضية:false
first_frame_image_urlstring
مطلوب
عنوان URL لصورة الإطار الأول.
last_frame_image_urlstring
اختياري
عنوان URL لصورة الإطار الأخير؛ يتطلب مدة 5 ثوانٍ.
modelstring
مطلوب
معرّف النموذج.
output_resolutionstring
اختياري
دقة الإخراج.
القيم المسموح بها:720p, 1080p, 4k
القيمة الافتراضية: 720p
promptstring
مطلوب
وصف الفيديو.
نطاق:1 - 2500
kling-v3-turbo-image-to-video6 حقل
callback_urlstring
اختياري
رابط Webhook لإشعارات غير متزامنة.
duration_secondsinteger
اختياري
المدة بالثواني.
القيم المسموح بها:3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
القيمة الافتراضية: 5
first_frame_image_urlstring
مطلوب
عنوان URL لصورة الإطار الأول.
modelstring
مطلوب
معرّف النموذج.
output_resolutionstring
اختياري
دقة الإخراج.
القيم المسموح بها:720p, 1080p
القيمة الافتراضية: 720p
promptstring
مطلوب
وصف الفيديو.
نطاق:1 - 2500
القواعد الشرطية
تسري هذه المتطلبات عندما تتطابق جميع الشروط المدرجة.
-
عندما
model = kling-o1- مطلوب
- غير مقبول
output_resolution,negative_prompt,cfg_scale
-
عندما
model = kling-v2.1-master-image-to-video- مطلوب
- غير مقبول
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
عندما
model = kling-v2.1-pro- مطلوب
- غير مقبول
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
عندما
model = kling-v2.1-standard- مطلوب
- غير مقبول
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
عندما
model = kling-v2.5-turbo-image-to-video-pro- مطلوب
- غير مقبول
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
عندما
model = kling-v2.6- مطلوب
- غير مقبول
output_resolution,negative_prompt,cfg_scale,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
عندما
model = kling-v3-omni- مطلوب
- غير مقبول
negative_prompt,cfg_scale,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
عندما
model = kling-v3-turbo-image-to-video- مطلوب
- غير مقبول
enable_sound,aspect_ratio,negative_prompt,cfg_scale,last_frame_image_url,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
04
HTTP 202إنشاء قبول
POST /api/v1/kling/image_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/kling/image_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/kling/image_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": [
"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/kling/image_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"
},
"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/kling/image_to_video
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Authentication required"
}11
HTTP 401الأخطاء
GET /api/v1/kling/image_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/kling/image_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: kling-o1, kling-v2.1-master-image-to-video, kling-v2.1-pro, kling-v2.1-standard, kling-v2.5-turbo-image-to-video-pro, kling-v2.6, kling-v3-omni, kling-v3-turbo-image-to-video"
}13
HTTP 402الأخطاء
POST /api/v1/kling/image_to_video
مخطط الاستجابة
JSON
{
"properties": {
"error": {
"description": "رسالة خطأ قابلة للقراءة البشرية.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}مثال على الاستجابة
JSON
{
"error": "Insufficient balance"
}14
HTTP 429الأخطاء
POST /api/v1/kling/image_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/kling/image_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/kling/image_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/kling/image_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/kling/image_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/kling/image_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-kling
PYTHON
import os
from runapi.kling import KlingClient
client = KlingClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.image_to_video.create(
model="kling-o1",
prompt="A gentle camera pan across the scene.",
first_frame_image_url="https://file.runapi.ai/first-frame.png"
)