> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# واجهة برمجة تطبيقات مزامنة الشفاه من Kling (Kling Lip Sync)

> Kling video generation API guide - Ace Data Cloud

اجعل **فيديو Kling موجودًا بالفعل** (5 ثوانٍ أو 10 ثوانٍ) "يتحدث" وفقًا للصوت أو النص — أي مزامنة الشفاه (Lip Sync). وبالاقتران مع `image2video` في `/kling/videos` (لجعل الصور تتحرك)، يمكن ربطها في سير عمل كامل لـ "**صور تتحدث / تقديم رقمي بشري**".

> هذه الواجهة عبارة عن تغليف ملائم بخطوة واحدة توفره AceDataCloud، وموجه لسيناريوهات التشغيل الشائعة بالصوت/النص؛ وهي ليست مطابقة للحقول الخاصة بواجهة Kling الرسمية متعددة الخطوات «التعرف على الوجه → Advanced Lip Sync». يُرجى الاعتماد على جدول المعلمات في هذه الصفحة.

* **عنوان الواجهة**: `POST https://api.acedata.cloud/kling/lip-sync`
* **تنسيق الطلب**: `application/json`
* **تنسيق الاستجابة**: `application/json`
* **الفوترة**: **2.45 Credits** لكل استدعاء ناجح (ثابتة)

## رؤوس الطلب (Request Headers)

| الحقل | القيمة | الوصف |
| - | - | - |
| `authorization` | `Bearer ${API_KEY}` | مفتاح API الخاص بك، [رابط الحصول عليه](https://platform.acedata.cloud) |
| `content-type` | `application/json` | تنسيق جسم الطلب |
| `accept` | `application/json` | تنسيق الاستجابة |

## معلمات الطلب (Request Body)

| المعلمة | النوع | مطلوب | الافتراضي | الوصف |
| - | - | - | - | - |
| `mode` | string | نعم | — | وضع التوليد. القيم: `audio2video` (مدفوع بالصوت)، `text2video` (مدفوع بالنص) |
| `video_id` | string | أحدهما | — | معرّف فيديو تم توليده بواسطة Kling (مثل `video_id` الذي يعيده image2video في `/kling/videos`). **يدعم فقط فيديوهات 5s/10s المُولّدة خلال 30 يومًا**. اختر أحد `video_id` و`video_url`، ولا يمكن تمريرهما معًا |
| `video_url` | string | أحدهما | — | رابط فيديو متاح للعامة. القيود: `.mp4`/`.mov`، ≤100MB، مدة 2–10s، بدقة 720p/1080p فقط، وأبعاد الجانب 720–1920px. اختر أحده و`video_id` |
| `audio_url` | string | مشروط | — | عنوان URL لتنزيل الصوت المحرّك، مطلوب عند `audio2video` + `audio_type=url`. الصيغ `.mp3`/`.wav`/`.m4a`/`.aac`، ≤5MB |
| `audio_type` | string | لا | `url` | طريقة نقل الصوت. القيم: `url`، `file` (تسري عند `audio2video`) |
| `audio_file` | string | مشروط | — | Base64 لملف الصوت، مطلوب عند `audio_type=file`. الصيغة كما سبق، ≤5MB |
| `text` | string | مشروط | — | النص المراد قراءته، مطلوب عند `text2video`، **بحد أقصى 120 حرفًا** |
| `voice_id` | string | مشروط | — | معرّف نبرة الصوت، مطلوب عند `text2video` |
| `voice_language` | string | لا | `zh` | لغة نبرة الصوت. القيم: `zh`، `en` (تسري عند `text2video`) |
| `voice_speed` | float | لا | `1.0` | سرعة الكلام، ضمن النطاق `0.8`–`2.0`، بدقة منزلة عشرية واحدة (تسري عند `text2video`) |
| `callback_url` | string | لا | — | عنوان رد النداء. عند تمرير هذا العنصر أو `async=true` تكون **وضعية غير متزامنة**: يُعاد `task_id` فورًا، ويتم رد النداء بعد توليد النتيجة |
| `async` | boolean | لا | `false` | ما إذا كان التنفيذ غير متزامن. عند `true` يُعاد `task_id` فورًا، مع الاستعلام الدوري عبر `/kling/tasks` أو رد النداء عبر `callback_url` |

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

### 1) التشغيل بالصوت (audio2video)

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/kling/lip-sync' \
  -H 'authorization: Bearer ${API_KEY}' \
  -H 'content-type: application/json' \
  -d '{
    "mode": "audio2video",
    "video_id": "895055164389466178",
    "audio_url": "https://cdn.acedata.cloud/6f7d62b18b.wav"
  }'
```

### 2) التشغيل بالنص (text2video)

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/kling/lip-sync' \
  -H 'authorization: Bearer ${API_KEY}' \
  -H 'content-type: application/json' \
  -d '{
    "mode": "text2video",
    "video_id": "895055164389466178",
    "text": "哥，好久不见，我一切都好，你要照顾好自己。",
    "voice_id": "genshin_vindi2",
    "voice_language": "zh",
    "voice_speed": 1.0
  }'
```

## مثال الاستجابة (نجاح متزامن)

```json theme={null}
{
  "success": true,
  "task_id": "07a3ec65-9f7e-4a09-b7b7-282684082527",
  "video_id": "895055968777281546",
  "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.mp4",
  "duration": "4.966",
  "state": "succeed"
}
```

| الحقل | النوع | الوصف |
| - | - | - |
| `success` | boolean | ما إذا كانت العملية ناجحة |
| `task_id` | string | معرّف هذه المهمة (يمكن استخدامه للاستعلام عبر `/kling/tasks`) |
| `video_id` | string | معرّف Kling للفيديو المُولَّد (يمكن استخدامه كمدخل لـ `extend`/`lip-sync` التالي) |
| `video_url` | string | رابط URL لفيديو التحدث المُولَّد (تم تخزينه على CDN هذه المنصة، وصالح لمدة طويلة) |
| `duration` | string | مدة الفيديو (بالثواني) |
| `state` | string | حالة المهمة: `succeed` / `failed` |

## الوضع غير المتزامن والاستعلام

عند تمرير `callback_url` أو `async: true`، تعيد الواجهة **فورًا** `task_id`؛ وبعد ذلك يمكن:

* **الاستعلام الدوري**: `POST /kling/tasks`، الجسم `{ "action": "retrieve", "id": "<task_id>" }` (مجاني)
* **رد النداء**: بعد اكتمال التوليد، تُرسل النتيجة عبر POST إلى `callback_url` الخاص بك

## العملية الكاملة: صور تتحدث (image2video → lip-sync)

```bash theme={null}
# 第 1 步：让照片动起来，拿到 video_id
curl -X POST 'https://api.acedata.cloud/kling/videos' \
  -H 'authorization: Bearer ${API_KEY}' -H 'content-type: application/json' \
  -d '{"model":"kling-v2-1-master","action":"image2video","start_image_url":"https://cdn.acedata.cloud/4hfydw.jpg","prompt":"look at camera, natural","duration":5,"mode":"pro"}'
# → { "video_id": "895055164389466178", ... }

# 第 2 步：用音频对口型
curl -X POST 'https://api.acedata.cloud/kling/lip-sync' \
  -H 'authorization: Bearer ${API_KEY}' -H 'content-type: application/json' \
  -d '{"mode":"audio2video","video_id":"895055164389466178","audio_url":"https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3"}'
# → { "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.mp4", ... }
```

## استجابة الخطأ

```json theme={null}
{
  "success": false,
  "error": { "code": "bad_request", "message": "one of video_id or video_url is required" },
  "trace_id": "f07cab09-3c18-4d74-9030-64ee840d9f16",
  "task_id": "f490537f-2e5c-4739-8149-6252fba2091c"
}
```

| HTTP | code | المعنى |
| - | - | - |
| 400 | `bad_request` | المعلمات مفقودة أو غير صالحة (مثل عدم تمرير mode، أو تعارض الاختيار بين video و audio، أو تجاوز text لـ 120 حرفًا) |
| 401 | `authorization_missing` | مفتاح API مفقود أو غير صالح |
| 403 | `forbidden` | تم حظر المحتوى بواسطة التحكم في المخاطر |
| 429 | `too_many_requests` | حد التزامن في المصدر، يُرجى إعادة المحاولة لاحقًا |
| 500 | `api_error` | خطأ في المصدر أو خطأ داخلي |

## ملاحظات

* يجب أن يكون `video_id` لفيديو قابل تم إنشاؤه خلال **30 يومًا**، وأن تكون مدته **5 ثوانٍ أو 10 ثوانٍ**؛ وإلا يُرجى استخدام `video_url` لتمرير فيديو يستوفي القيود.
* يُنصح بأن يكون فيديو الإدخال **لوجه أمامي واضح، وشخص واحد**، للحصول على أفضل تأثير لمزامنة حركة الشفاه.
* يجب أن تتوافق مدة الصوت/النص مع مدة الفيديو (ألا يتجاوز الصوت طول الفيديو).
* تتم الفوترة عند **النجاح** (2.45 Credits/مرة)؛ ولا تُفرض رسوم عند فشل التحقق من المعلمات (4xx).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.