واجهة برمجة تطبيقات OmniHuman v1.5: توليد مقاطع فيديو الأفاتار برمجياً

تشغيل OmniHuman v1.5 عبر واجهة Arteza رائع للإنشاء الفردي. أما لسير العمل عالي الحجم، كالتواصل المبيعاتي المخصص، والإطلاق متعدد اللغات، وتوليد الفيديو المدفوع بنظام إدارة المحتوى، وملخصات الأخبار الآلية، فإن الـ API هو الخيار الأمثل. يستعرض هذا الدليل المصادقة، ونقاط النهاية، وبنية الطلبات، ومعالجة الـ webhook، وأنماط الإنتاج. كل عملية توليد تكلف 3-72 كريدت ($0.30-$7.20) سواء استخدمت الواجهة أو الـ API.

ملخص سريع

• توليد مقاطع فيديو OmniHuman v1.5 برمجياً عبر Arteza REST API
• نفس تسعير $0.30-$7.20 لكل عملية توليد كما في الواجهة، بدون رسوم إضافية على الـ API
• توليد غير متزامن مع استرداد النتائج عبر webhook أو الاستطلاع الدوري
• مثالي لمقاطع المبيعات المخصصة، ومكتبات التدريب الآلية، والإطلاق متعدد اللغات
• المصادقة عبر مفتاح API من لوحة تحكم Arteza

لماذا تستخدم الـ API

يتيح الـ API أنماط أتمتة لا تستطيع الواجهة مجاراتها:

• التوليد الدُفعي. شغّل أكثر من 100 مقطع فيديو في تشغيل واحد للمسار.
• التخصيص الديناميكي. اسحب البيانات من نظام CRM وأنشئ مقطع فيديو لكل عميل محتمل.
• سير العمل المجدول. ملخصات أخبار يومية، ومقاطع ملخصة أسبوعية، وتحديثات مُشغَّلة تلقائياً.
• التكامل مع الأنظمة الحالية. Node.js وPython وGo وRuby، أي لغة تدعم HTTP يمكنها استدعاؤه.
• إنتاج قابل للتكرار. سكريبتات خاضعة لإدارة الإصدارات بدلاً من النقرات اليدوية في الواجهة.

إذا كانت حالة استخدامك تتضمن أكثر من 10 مقاطع فيديو بهيكل متشابه، فإن إعداد الـ API يستحق العناء.

المصادقة

تتم مصادقة طلبات Arteza API عبر مفتاح API يُمرَّر في ترويسة Authorization كرمز Bearer.

الحصول على مفتاح الـ API

1. سجّل الدخول على arteza.ai
2. انتقل إلى إعدادات حسابك
3. ابحث عن قسم الـ API
4. أنشئ مفتاح API جديداً
5. احفظه بأمان، وتعامل معه كلمة مرور

لا تُدرج مفتاح الـ API في نظام التحكم بالمصدر أبداً. استخدم متغيرات البيئة:

export SEEDANCE_API_KEY="your_api_key_here"

ترويسة المصادقة

يتضمن كل طلب:

Authorization: Bearer YOUR_SEEDANCE_API_KEY
Content-Type: application/json

بنية نقاط النهاية

يتبع OmniHuman v1.5 API أنماط التوليد غير المتزامن القياسية:

• POST لإنشاء مهمة توليد
• GET للاستطلاع الدوري عن الحالة والنتائج
• Webhook للتسليم غير المتزامن (موصى به للإنتاج)

الرابط الأساسي

https://api.arteza.ai/v1

نقاط النهاية الرئيسية

راجع وثائق Arteza API الحية للاطلاع على مسارات نقاط النهاية الدقيقة، إذ قد تتطور المسارات مع الوقت.

إرسال مهمة توليد

بنية الطلب

{
  "model": "omnihuman-v1.5",
  "image_url": "https://example.com/portrait.jpg",
  "audio_url": "https://example.com/speech.mp3",
  "prompt": "Modern corporate office with soft natural lighting, medium close-up framing head and shoulders, professional broadcast style",
  "resolution": "1080p",
  "turbo_mode": false,
  "webhook_url": "https://yourapp.com/webhooks/seedance"
}

مرجع المعاملات

متطلبات ملفات الإدخال

الصورة:

• الصيغ: JPEG، PNG
• الدقة: 512x512 كحد أدنى، يُنصح بـ 1024x1024 أو أعلى
• يجب أن تكون متاحة عبر رابط HTTPS عام

الصوت:

• الصيغ: MP3، WAV، M4A
• المدة: ≤60 ثانية لدقة 720p، و≤30 ثانية لدقة 1080p
• يجب أن يكون متاحاً عبر رابط HTTPS عام

إذا لم تكن ملفاتك مستضافة بشكل عام بعد، فارفعها إلى S3 أو Cloudflare R2 أو Google Cloud Storage أو ما شابه ذلك قبل إجراء استدعاء API.

مثال على الطلب بلغة Python

import os
import requests

SEEDANCE_API_KEY = os.environ["SEEDANCE_API_KEY"]
BASE_URL = "https://api.arteza.ai/v1"

def create_omnihuman_video(image_url, audio_url, prompt,
                           resolution="1080p", turbo=False):
    headers = {
        "Authorization": f"Bearer {SEEDANCE_API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "model": "omnihuman-v1.5",
        "image_url": image_url,
        "audio_url": audio_url,
        "prompt": prompt,
        "resolution": resolution,
        "turbo_mode": turbo,
    }
    response = requests.post(
        f"{BASE_URL}/omnihuman/generate",
        json=payload,
        headers=headers,
    )
    response.raise_for_status()
    return response.json()

job = create_omnihuman_video(
    image_url="https://cdn.example.com/ceo.jpg",
    audio_url="https://cdn.example.com/weekly-update.mp3",
    prompt="Corporate office with warm lighting, medium close-up, professional style",
)
print(f"Job submitted: {job['job_id']}")

مثال على الطلب بلغة Node.js

import fetch from "node-fetch";

const SEEDANCE_API_KEY = process.env.SEEDANCE_API_KEY;
const BASE_URL = "https://api.arteza.ai/v1";

async function createOmnihumanVideo({
  imageUrl,
  audioUrl,
  prompt,
  resolution = "1080p",
  turbo = false,
}) {
  const response = await fetch(`${BASE_URL}/omnihuman/generate`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${SEEDANCE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "omnihuman-v1.5",
      image_url: imageUrl,
      audio_url: audioUrl,
      prompt,
      resolution,
      turbo_mode: turbo,
    }),
  });

  if (!response.ok) {
    throw new Error(`Arteza API error: ${response.status}`);
  }
  return response.json();
}

const job = await createOmnihumanVideo({
  imageUrl: "https://cdn.example.com/ceo.jpg",
  audioUrl: "https://cdn.example.com/update.mp3",
  prompt: "Modern office, soft lighting, medium close-up",
});
console.log(`Job submitted: ${job.job_id}`);

صيغة الاستجابة

{
  "job_id": "job_abc123xyz",
  "status": "queued",
  "created_at": "2026-04-10T14:23:00Z",
  "estimated_credits": 46
}

يُستخدم job_id للاستطلاع أو لربط تسليمات الـ webhook.

الاستطلاع للحصول على النتائج

إذا لم تكن تستخدم الـ webhooks، فاستطلع نقطة نهاية حالة المهمة حتى تكتمل.

import time

def wait_for_video(job_id, timeout_seconds=600, poll_interval=5):
    headers = {"Authorization": f"Bearer {SEEDANCE_API_KEY}"}
    deadline = time.time() + timeout_seconds

    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/jobs/{job_id}",
            headers=headers,
        )
        response.raise_for_status()
        data = response.json()
        status = data["status"]

        if status == "completed":
            return data["result"]["video_url"]
        if status == "failed":
            raise Exception(f"Generation failed: {data.get('error')}")

        time.sleep(poll_interval)

    raise TimeoutError("Job did not complete within timeout")

video_url = wait_for_video(job["job_id"])
print(f"Video ready: {video_url}")

قيم حالة المهمة

استخدام الـ webhooks (موصى به للإنتاج)

تُلغي الـ webhooks الحاجة إلى الاستطلاع وتتيح لك بناء مسارات عمل مدفوعة بالأحداث.

إعداد الـ webhook

مرر webhook_url في طلب التوليد الخاص بك. يقوم Seedance بإرسال طلب POST إلى ذلك الرابط عند اكتمال المهمة.

حمولة الـ webhook

{
  "event": "job.completed",
  "job_id": "job_abc123xyz",
  "status": "completed",
  "result": {
    "video_url": "https://cdn.arteza.ai/outputs/video_abc123.mp4",
    "resolution": "1080p",
    "duration_seconds": 28.5
  },
  "credits_used": 46,
  "completed_at": "2026-04-10T14:26:45Z"
}

مثال على معالج Webhook

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/seedance", methods=["POST"])
def seedance_webhook():
    payload = request.get_json()

    if payload.get("event") == "job.completed":
        job_id = payload["job_id"]
        video_url = payload["result"]["video_url"]

        # منطق العمل الخاص بك: تنزيل الفيديو، إشعار المستخدمين،
        # تشغيل سير العمل اللاحقة، وما إلى ذلك.
        handle_completed_video(job_id, video_url)

    return jsonify({"received": True}), 200

أمان Webhook

تحقق من توقيعات Webhook إذا كانت Arteza توفر سرًا للتوقيع. تحقق دائمًا من أن Webhook قادم من Arteza قبل التصرف بناءً عليه.

هل أنت مستعد لتجربة OmniHuman v1.5؟ ابدأ الإنشاء مجاناً →

هل تريد مقدمًا كهذا؟ جرّب OmniHuman مجاناً →

أنماط الإنتاج

النمط الأول: خط أنابيب فيديو المبيعات المخصص

أنشئ فيديو واحدًا لكل عميل محتمل باستخدام متغيرات نصية ديناميكية.

def generate_sales_video_for_prospect(prospect):
    script = render_template("sales_template.txt", {
        "first_name": prospect["first_name"],
        "company": prospect["company"],
        "trigger": prospect["trigger_event"],
    })

    audio_url = generate_tts(script)

    job = create_omnihuman_video(
        image_url=YOUR_SDR_PHOTO_URL,
        audio_url=audio_url,
        prompt=STANDARD_SCENE_PROMPT,
        resolution="1080p",
    )
    return job["job_id"]

prospects = load_prospects_from_crm()
for prospect in prospects:
    generate_sales_video_for_prospect(prospect)

راجع دليل مقاطع الفيديو الترويجية للاطلاع على نصائح كتابة النصوص والتوزيع.

النمط الثاني: طرح المحتوى متعدد اللغات

أنشئ الرسالة ذاتها بلغات متعددة مع الصورة نفسها.

languages = [
    ("en", "english_audio.mp3"),
    ("es", "spanish_audio.mp3"),
    ("pt", "portuguese_audio.mp3"),
    ("fr", "french_audio.mp3"),
    ("de", "german_audio.mp3"),
]

jobs = []
for lang_code, audio_file in languages:
    audio_url = upload_to_cdn(audio_file)
    job = create_omnihuman_video(
        image_url=SPOKESPERSON_PHOTO_URL,
        audio_url=audio_url,
        prompt=STANDARD_PROMPT,
    )
    jobs.append((lang_code, job["job_id"]))

راجع الدليل متعدد اللغات للاطلاع على نصائح الصوت والترجمة.

النمط الثالث: أتمتة ملخص الأخبار اليومي

خط أنابيب مجدول يسحب العناوين الرئيسية وينشئ تحويل النص إلى كلام وينتج فيديو يوميًا.

from datetime import datetime

def daily_news_digest():
    headlines = fetch_top_headlines()
    script = format_headlines_as_script(headlines)
    audio_url = generate_tts(script, voice="broadcast_news")

    job = create_omnihuman_video(
        image_url=NEWS_ANCHOR_PHOTO_URL,
        audio_url=audio_url,
        prompt="Professional news studio, broadcast style, medium close-up",
        resolution="720p",
    )
    return job["job_id"]

# جدولة عبر cron أو Airflow أو أداة سير العمل الخاصة بك
daily_news_digest()

راجع دليل مذيع الأخبار.

النمط الرابع: توليد الفيديو المُشغَّل من نظام إدارة المحتوى

عند نشر مقالة مدونة أو منتج جديد، أنشئ فيديو مرافقًا له.

@app.route("/cms/published", methods=["POST"])
def on_content_published():
    content = request.get_json()
    script = summarize_content(content["body"])
    audio_url = generate_tts(script)

    job = create_omnihuman_video(
        image_url=BRAND_SPOKESPERSON_PHOTO,
        audio_url=audio_url,
        prompt=BRAND_SCENE_PROMPT,
        webhook_url="https://yourapp.com/webhooks/seedance",
    )
    store_job_mapping(content["id"], job["job_id"])
    return {"ok": True}

أفضل ممارسات معالجة الأخطاء

إعادة المحاولة مع التراجع الأسي

يجب أن تؤدي أخطاء الشبكة والأعطال المؤقتة إلى إعادة المحاولة، لا إلى التخلي الفوري.

import time

def create_with_retry(params, max_retries=3):
    delay = 2
    for attempt in range(max_retries):
        try:
            return create_omnihuman_video(**params)
        except requests.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(delay)
            delay *= 2

التحقق من المدخلات قبل الإرسال

وفّر رصيدك بالتحقق قبل كل استدعاء API:

• عنوان URL للصورة يُرجع 200 ونوع المحتوى image/*
• عنوان URL للصوت يُرجع 200 ونوع المحتوى audio/*
• مدة الصوت ضمن الحد المسموح به للدقة المختارة
• النص ليس فارغًا

التعامل مع حدود معدل الطلبات

تفرض واجهة API حدودًا على معدل الطلبات. احترم استجابات 429 وتراجع بشكل مناسب.

مراقبة رصيد الاعتمادات

تحقق من رصيد اعتماداتك قبل تشغيل دُفعات كبيرة. نفاد الاعتمادات في منتصف الدُفعة أمر يمكن تجنبه.

إدارة التكاليف

يكلف الفيديو المُنشأ عبر API 2.4 اعتماد في الثانية من الصوت، أي 72 اعتمادًا ($7.20) لمدة 30 ثانية. الاعتمادات ذاتها التي تشغّل الواجهة تشغّل API أيضًا:

بالنسبة لأحمال عمل API الثقيلة، تمنحك خطة Studio أفضل تكلفة فعلية لكل عملية توليد. راجع دليل الأسعار للاطلاع على التفاصيل.

تقدير تكلفة المشروع

قبل بدء تشغيل دُفعة، احسب التكلفة الإجمالية:

total_cost = number_of_videos * 4.60

دُفعة من 1,000 فيديو بمدة 30 ثانية لكل منها: $7,200 بالسعر الأساسي، وأقل بكثير مع خطة شهرية. ضع ميزانيتك وفقًا لذلك.

قابلية المراقبة

لسير العمل في بيئة الإنتاج، تتبع هذه المقاييس:

• معدل النجاح - نسبة الوظائف التي تكتمل بنجاح
• متوسط وقت التوليد - لتخطيط الطاقة الاستيعابية
• الاعتمادات المستهلكة - إجماليات متجددة لتتبع الميزانية
• معدل تسليم Webhook - اكتشاف إخفاقات تسليم Webhook
• تصنيف الأخطاء - تجميع الإخفاقات حسب السبب

سجّل معرّفات الوظائف إلى جانب معرّفات الارتباط الداخلية الخاصة بك لأغراض التصحيح.

أفضل ممارسات الأمان

• لا تكشف أبدًا عن مفتاح API على جانب العميل. استدعِ API دائمًا من الواجهة الخلفية.
• استخدم متغيرات البيئة أو مدير الأسرار. لا تُدرج المفاتيح أبدًا في التحكم بالمصدر.
• دوّر المفاتيح بشكل دوري. تعامل معها كأي بيانات اعتماد أخرى.
• تحقق من توقيعات Webhook عند توفرها.
• استخدم HTTPS لجميع عناوين URL للصور والصوت التي تمررها إلى API.
• حدد نطاق نقاط نهاية Webhook حتى تُعالَج فقط حمولات Arteza الشرعية.

البدء باستخدام API

1. سجّل في Arteza واجمع 10 اعتمادًا مجانيًا
2. اشترك في خطة Starter على الأقل ($5 شهريًا) للحصول على ما يكفي لاختبار التوليد
3. أنشئ مفتاح API الخاص بك في لوحة التحكم
4. جهّز صورة اختبارية وملف صوتي، وارفعهما إلى عنوان URL عام
5. أجرِ أول استدعاء API باستخدام الأمثلة أعلاه
6. استطلع أو انتظر Webhook لاسترداد عنوان URL للفيديو
7. ابنِ خط أنابيب الإنتاج الخاص بك

للاطلاع على قراءات ذات صلة، راجع الدليل الشامل لـ OmniHuman v1.5 وتفصيل الأسعار ودليل مقاطع الفيديو الترويجية والدليل متعدد اللغات.

هل أنت مستعد لتجربة OmniHuman v1.5؟ ابدأ الإنشاء مجاناً →