AiVideoEditor
ابدأ مجانًا
القائمة

رُوجع 2026-11-11 · إصدار API 2026-11-09 · قراءة Markdown

البداية السريعة لواجهة برمجة تطبيقات AiVideoEditor

عنوان URL الأساسي: https://<your-app-host>/api/v1 (بيئة التطوير المحلية: http://localhost:3006/api/v1).

المصادقة

أنشئ مفتاح منتج في Developers ضمن تنقّل مساحة العمل (/app/developers). يُعرض مفتاح النص الصريح (pk_v1_…) مرة واحدة بالضبط؛ ولا يُخزَّن سوى تجزئة (hash) وبادئة قصيرة. أرسله كرمز حامل (bearer token):

curl -H "Authorization: Bearer $PUBLISHER_KEY" https://app.example.com/api/v1/usage

تحمل المفاتيح نطاقات صريحة (accounts:read، media:write، posts:read، posts:write، posts:publish، usage:read، webhooks:manage) وقائمة سماح اختيارية للحسابات. مفتاح المسودات فقط يستبعد posts:publish ولذلك لا يمكنه النشر أو الجدولة أو الإلغاء أو إعادة المحاولة. لا يمكن للمفاتيح أبدًا إنشاء مفاتيح أخرى أو تغيير الفوترة. إبطال مفتاح يوقف مهامه غير المرسلة بحالة requires_action: لا يُحذف شيء، وتعرض واجهة الإبطال عدد المهام المعلقة المتأثرة أولًا.

القواعد الأساسية

  • كل عملية تغيير تتطلب ترويسة Idempotency-Key. المفتاح نفسه + الجسم نفسه ← النتيجة المسجّلة نفسها (معرّفات التسليم نفسها). المفتاح نفسه + جسم مختلف ← 409 idempotency_conflict.
  • تتطلب التحريرات والجدولة expectedVersion؛ ويعيد الإصدار القديم 409 revision_conflict مع الإصدار الحالي في error.details.currentVersion.
  • تعني 202 من النشر/الجدولة القبول للإرسال، وليست "نشرًا" أبدًا. تتبّع النتائج باستخدام GET /posts/{id} أو خطافات الويب للعملاء أو الاستقصاء المحدود.
  • حدود المعدل هي حدود سرعة تقنية لكل مساحة عمل (60/120/240 طلبًا/دقيقة حسب الخطة؛ 429 + Retry-After). لا توجد حصة طلبات أو نشر: النشر غير محدود في كل خطة مدفوعة.
  • تستخدم الأخطاء الغلاف الموحّد: { error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }.

من البداية إلى النهاية: مسودة ← تحقق ← نشر ← مراقبة

يتطلب المثال Bash وcurl وjq وNode 22+ ومساحة عمل نشطة، ووجهة Facebook Page أو LinkedIn مرتبطة، ومفتاحًا يملك accounts:read وposts:read وposts:write وposts:publish. اضبط ACCOUNT_ID على وجهة مسموح بها من /accounts؛ وتحقق من دعم تنسيق النص لديها في /capabilities. تشغيل أمر النشر ينشر محتوى حقيقيًا.

set -euo pipefail
BASE="${PUBLISHER_API_URL:?Set the AiVideoEditor origin}/api/v1"
AUTH="Authorization: Bearer ${PUBLISHER_KEY:?Set the product key}"
JSON="Content-Type: application/json"
new_key() { node -e 'console.log(require("node:crypto").randomUUID())'; }

curl --fail-with-body -sS -H "$AUTH" "$BASE/accounts"
curl --fail-with-body -sS -H "$AUTH" "$BASE/capabilities"
: "${ACCOUNT_ID:?Choose a permitted text destination from the responses above}"

# Save this key and body; reuse both if the connection fails ambiguously.
CREATE_KEY=$(new_key)
DRAFT_BODY=$(jq -n --arg account "$ACCOUNT_ID" '{caption:"A new update from our team.",mediaIds:[],brandFolderId:null,destinations:[{accountId:$account,format:"text"}]}')
DRAFT=$(curl --fail-with-body -sS -X POST -H "$AUTH" \
  -H "Idempotency-Key: $CREATE_KEY" -H "$JSON" \
  "$BASE/posts" -d "$DRAFT_BODY")
POST_ID=$(jq -er '.post.postId' <<<"$DRAFT")
VERSION=$(jq -er '.post.version' <<<"$DRAFT")

VALIDATION=$(curl --fail-with-body -sS -X POST -H "$AUTH" "$BASE/posts/$POST_ID/validate")
printf '%s\n' "$VALIDATION"
jq -e '.validation.valid == true' <<<"$VALIDATION" >/dev/null

# 202 means accepted. Keep this key for an identical retry after a timeout.
PUBLISH_KEY=$(new_key)
ACCEPTED=$(curl --fail-with-body -sS -X POST -H "$AUTH" \
  -H "Idempotency-Key: $PUBLISH_KEY" "$BASE/posts/$POST_ID/publish")
printf '%s\n' "$ACCEPTED"
curl --fail-with-body -sS -H "$AUTH" "$BASE/posts/$POST_ID"

لوجهات الصور/الفيديو، ارفع الوسائط وأنهِها أولًا، ثم استخدم معرّفات الأصول المُعادة في mediaIds مع تنسيق وجهة مؤهل. راقب معرّفات التسليم الفردية من الاستجابة المقبولة؛ واستخدم خطافات الويب أو استقصاء حالة محدودًا مع تراجع متزايد. قد تبقى قراءة حالة فورية واحدة قيد الانتظار.

الجدولة بدلًا من النشر

استخدم هذا على مسودة بدلًا من خطوة النشر أعلاه. اجلب إصدارها الحالي مرة أخرى بعد أي تحرير. يحسب هذا لحظة مستقبلية بدلًا من استخدام تاريخ نموذجي سينتهي.

SCHEDULED_AT=$(node -e 'console.log(new Date(Date.now()+86400000).toISOString())')
SCHEDULE_BODY=$(jq -n --arg at "$SCHEDULED_AT" --argjson version "$VERSION" \
  '{scheduledAt:$at,timezone:"America/Indiana/Indianapolis",expectedVersion:$version}')
SCHEDULE_KEY=$(new_key)
curl --fail-with-body -sS -X POST -H "$AUTH" -H "Idempotency-Key: $SCHEDULE_KEY" \
  -H "$JSON" "$BASE/posts/$POST_ID/schedule" -d "$SCHEDULE_BODY"

يجب أن تكون اللحظة مستقبلية وضمن أفق 90 يومًا؛ وتُخزَّن لحظة UTC والمنطقة الزمنية للعرض بشكل منفصل. إذا انتهت صلاحية مفتاح API عند تلك اللحظة أو قبلها، فقد تضمنت الاستجابة المقبولة إدخال warnings بالرمز key_expires_before_schedule. يبقى التسليم مجدولًا، لكن يجب مراجعته وإعادة إرساله تحت ممثل نشط قبل أن يتمكن من النشر. يُحفظ التحذير نفسه عند إعادة تشغيل الطلب. ألغِ ما دام العمل غير مطالب به بأمان:

curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/cancel
# Already submitted? → 409 too_late_to_cancel with the real state.

أعد المحاولة فقط لوجهة فشل معروفة (الحالات المجهولة/الناجحة تُرفض):

curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/retry

الوسائط (تحميلات مباشرة)

بايتات الوسائط لا تمر عبر هذه الواجهة أبدًا.

# 1. Reserve bytes → direct instructions (presigned PUT, or multipart for large files)
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/upload-intents -d '{
  "filename": "poster.jpg", "declaredMime": "image/jpeg", "declaredBytes": 1048576 }'

# 2. Upload bytes DIRECTLY to the returned URL with the documented method.

# 3. Finalize: the server verifies size/signature on the immutable final copy.
#    Send ONLY the session identity (plus part receipts for multipart uploads)
#: bytes, MIME and checksum are observed server-side, never declared here.
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/$ASSET_ID/finalize -d '{
  "sessionId": "…" }'

# multipart: include the ETag receipt of every uploaded part.
# Files at or above 50 MiB use multipart; use the returned part size and URLs.
# Upload every part and retain its ETag. Small files finalize with sessionId only.
# These are alternative finalization shapes, not two consecutive operations.
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/$ASSET_ID/finalize -d '{
  "sessionId": "…",
  "multipart": { "parts": [ { "partNumber": 1, "etag": "…" } ] } }'

# 4. Status/expiry only: there is no permanent public media URL
curl -s -H "$AUTH" $BASE/media/$ASSET_ID

الملفات مؤقتة: تحافظ المنشورات المجدولة على وسائطها عبر النشر، ويُعرض deleteAfter الديناميكي (أو null) دائمًا. احتفظ بنسخك الأصلية.

الاستخدام

يعرض GET /usage الخطة وفتحات الحسابات المرتبطة/المحجوزة والأعضاء والتخزين وأفق 90 يومًا ومعلومات المعدل. أرقام النشاط مقاييس تشغيلية فقط: لا يوجد عدّاد منشورات متبقية في أي مكان داخل المنتج.

ترقيم الصفحات

تستخدم نقاط نهاية القوائم مؤشرات غير شفافة: ?limit=25&cursor=<nextCursor>. الطوابع الزمنية بصيغة UTC ISO-8601. تابع حتى يصبح nextCursor بقيمة null؛ وقد تكون صفحة منشورات مفلترة فارغة بينما يشير مؤشرها غير الفارغ إلى سجلات أقدم ما زال يجب مسحها. فضّل خطافات الويب (راجع خطافات الويب) أو الاستقصاء المحدود مع التراجع على حلقات الحالة الضيقة.

الحدود والنجاح الجزئي

قدرات الوجهة (من GET /capabilities) تحمل أشد الحدود الفعالة صرامةً: التطبيق والمزوّد والشبكة والحساب. عندما تمنع حدودٌ ما طلبًا، يكون غلاف الخطأ قابلًا للتصرف بناءً عليه:

{
  "error": {
    "code": "storage_limit",
    "message": "Active temporary media exceeds this plan's storage allowance.",
    "retryable": false,
    "requestId": "…"
  }
}

account_limit وseat_limit وstorage_limit وsubscription_inactive وtrial_expired استجابات 402؛ لا يُحذف شيء، وتُحفظ المسودات/العمل المدرول لما بعد الترقية.

النشر/الجدولة دفعة من مهام وجهات مستقلة. النجاح الجزئي طبيعي ويُبلَّغ عنه لكل وجهة: وليس أبدًا وعدًا ذرّيًا:

{
  "post": {
    "postId": "…",
    "version": 4,
    "status": "partially_published",
    "deliveries": [
      { "id": "…", "accountId": "…", "network": "instagram", "state": "published",
        "nativePostUrl": "https://instagram.com/p/…", "unresolvedExternalOutcome": false },
      { "id": "…", "accountId": "…", "network": "linkedin", "state": "reconnect_required",
        "nativePostUrl": null, "lastErrorCode": "reconnect_required" }
    ]
  },
  "requestId": "…"
}

أعد المحاولة فقط للوجهة الفاشلة (POST /deliveries/{id}/retry)؛ الوجهات الناجحة لا تُرسل مرة أخرى أبدًا. تعيد متطلبات الموافقة/إعادة الربط requires_action مع تعليمات آمنة، وليس أبدًا سرًّا.

المرجع الكامل

بالنسبة إلى TikTok، تعيد GET /accounts/{id}/tiktok/settings خيارات الخصوصية الحالية للمنشئ المرتبط وأذونات التفاعل وحد المدة وتوافر وضع النشر. يتطلب accounts:read ويحترم قائمة سماح المفتاح. حفظ مسودة أو قراءة هذه الإعدادات لا يوفر الموافقة.

النشر/الجدولة دون تأكيد بشري حالي يعيد HTTP 409 consent_required مع error.requiresAction.url يشير إلى المسودة المحفوظة في محرِّر التأليف المصادق عليه. يمكن للتحقق أن يعيد التسليم نفسه جنبًا إلى جنب مع مشكلاته المهيكلة. يراجع الشخص الفيديو/نص المنشور بالضبط ويتخذ خياراته الصريحة هناك؛ ولا يمكن لمفاتيح المنتج وMCP التأكيد نيابة عنه. بعد تأكيد الشخص، أعد المحاولة عبر خدمة النشر المشتركة العادية. تحرير المحتوى أو تغيير هوية الوجهة يتطلب مراجعة جديدة. عنوان URL للتسليم لا يحتوي على مفتاح منتج أو رمز أو عنوان URL وسائط موقّع، ولا يمنح أي وصول لشخص يفتقر إلى عضوية مساحة العمل. يحدد معرّف UUID لمساحة العمل فيه مساحة عمل المفتاح؛ يجب على متصفح بمساحة عمل محددة مختلفة أن يبدّل صريحًا بعد فحص عضوية حالية قبل مراجعة هذه المسودة.

راجع مواصفات OpenAPI للعقد الكامل والحالي. تقرأ واجهة المستخدم وREST وMCP الخدمات نفسها، لذا تطبق قواعد مساحة العمل نفسها. تعكس النتائج الحالة الحالية لكل طلب؛ ويمكن للطلبات المنفصلة ملاحظة تحديثات واقعة بينها.