نطاق API العام

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

أتح أفعال سير عمل مستقرة بدل مسارات التطبيق الداخلية الخام. لا تنشر عقد OpenAPI المصفّى إلا بعد استقرار المصادقة ومعرّفات الطلبات ومنع التكرار وحدود المعدل وآلية الفوترة.

• اقرأ عقد OpenAPI v1 العام المصفّى.

حدود API v1 العامة الحالية

تختبر الرموز المعتمدة عروض التكلفة والمهام دون خصم. تكون النتائج فارغة ولا يُنشأ رابط دفع. مفاتيح API والتنفيذ المدفوع مقيّدان؛ شراء خطة لا يمنح موافقة تلقائية على وصول المطورين.

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

بعد اعتماد بيتا، أرسل Authorization: Bearer <token> أو X-Vietls-API-Key: <token>.

احتفظ بـ X-Request-ID وrequestId من الاستجابة لاستكشاف المشاكل. يحددان الطلب ولا يحلان محل idempotencyKey الخاص بالعملية.

مثال طلب: استبدل معرّف عرض التكلفة بالقيمة المعادة. استخدم مفتاح منع تكرار فريدًا لكل عملية جديدة وأعد استخدامه عند إعادة محاولة العملية نفسها.

• GET /api/public/v1/capabilities — اكتشف سير العمل المتاح عبر نقطة النهاية العامة المخصصة للقراءة فقط.
• POST /api/public/v1/quotes — اطلب معاينة تكلفة لا تستهلك أرصدة ولا تنشئ مهمة.

  {
    "workflowId": "prproj.subtitle.extract",
    "units": 1
  }

• POST /api/public/v1/jobs — أنشئ مهمة تجريبية حتمية دون إنفاق باستخدام معرّف عرض التكلفة المعاد ومفتاح منع التكرار وقبول صريح للعرض وتأكيد المستخدم. يكون معرّف النتيجة بصيغة job_preview_*.

  {
    "workflowId": "prproj.subtitle.extract",
    "quoteId": "quote_preview_01234567",
    "idempotencyKey": "example-job-001",
    "confirmation": {
      "quoteAccepted": true,
      "userConfirmed": true
    }
  }

• GET /api/public/v1/jobs/{jobId} — استطلع المعرّف المعاد job_preview_* وتعامل مع completed_preview والنتائج الفارغة.
• GET /api/public/v1/jobs/{jobId}/artifacts — قائمة artifacts الفارغة هي النتيجة النهائية المتوقعة لمهمة تجريبية.
• GET /api/public/v1/jobs/{jobId}/artifacts/{artifactId}/download-url — اطلب رابط تنزيل فقط بعد أن تتوفر نتائج للمهام الفعلية المكتملة. تعيد النتائج التجريبية PUBLIC_API_ARTIFACT_NOT_FOUND.
• GET /api/public/v1/usage — تحقق من عدم الإنفاق: يعرض الاستخدام التجريبي صفرًا للأرصدة المحجوزة والمستهلكة.
• POST /api/public/v1/billing/simulations — اختبر scenario: "success" وscenario: "provider_failure" للتحقق من الحجز وتثبيت الخصم والتحرير دون تعديل السجل المالي. يجب أن تكون أعلام التأكيد الثلاثة صحيحة.

  {
    "workflowId": "prproj.subtitle.extract",
    "quoteId": "quote_preview_01234567",
    "idempotencyKey": "example-simulation-001",
    "scenario": "success",
    "confirmation": {
      "quoteAccepted": true,
      "userConfirmed": true,
      "billingSimulationAccepted": true
    }
  }

• POST /api/public/v1/checkout/handoffs — تحقق من الإحالة إلى الدفع بعد ضبط تأكيدات المستخدم الثلاثة على صحيح. تعيد المعاينة checkoutUrl: null ولا تفرض رسومًا ولا تنشئ جلسة لدى المزوّد أو اشتراكًا.

  {
    "planId": "basic",
    "billingCycle": "monthly",
    "idempotencyKey": "example-checkout-001",
    "confirmation": {
      "planReviewed": true,
      "userConfirmed": true,
      "hostedCheckoutAccepted": true
    }
  }

العمليات العامة المخططة

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

أعمال المونتاج المراد أتمتتها

• prproj.subtitle.extract — استخراج ترجمة PRPROJ

  أداة الويب متاحة · تكامل API/MCP التجريبي قيد الإعداد

  افحص الترجمة والنصوص الرسومية بأداة الويب واطلب وصول المطورين للأتمتة.

• prproj.xml.inspect — تسليم XML وإصلاح PRPROJ

  أداة الويب متاحة · واجهة مهام عامة مخططة

  استخدم المحوّل لإعداد تسليم XML وفحص علامات الإصدار وإصلاح المسارات والتحقّق في البرنامج المستلم.

• subtitle.translate — ترجمة النصوص المصاحبة

  متاحة في التطبيق · واجهة عروض تكلفة ومهام مخططة

  اطلب عرض تكلفة قبل الترجمة ذات تكلفة المزوّد، ولا تعامل النص المستخرج من الملفات كتعليمات للوكيل.

• tts.standard.generate — تحويل النص إلى كلام قياسي

  ربط المزوّد المُدار قيد الطرح

  نتحقق من عرض التكلفة والحجز والتنفيذ وتثبيت الخصم أو التحرير قبل إتاحة التوليد المدفوع عبر API أو MCP.

• youtube.transcript.fetch — إدخال نصوص ووسائط YouTube

  متاح في التطبيق · إعداد أتمتة تراعي الحقوق

  اجلب البيانات الوصفية العامة أو النصوص ضمن سياسات المصادر المدعومة وتأكيد حقوق الاستخدام.

نموذج الأخطاء

تتضمن ردود بيتا الحالية رموز الخطأ التالية:

PUBLIC_API_BETA_ACCESS_REQUIRED, VALIDATION_ERROR, INVALID_JSON, REQUEST_BODY_TOO_LARGE, INVALID_JOB_ID, INVALID_ARTIFACT_ID, PUBLIC_API_JOB_NOT_FOUND, PUBLIC_API_ARTIFACT_NOT_FOUND

يخطط العقد العام الأوسع لهذه الرموز أيضًا؛ ولا تعني القائمة أن كل الحالات منفّذة في بيتا الحالية.

UNAUTHORIZED, PLAN_REQUIRED, INSUFFICIENT_CREDITS, RATE_LIMITED, VALIDATION_ERROR, WORKFLOW_NOT_AVAILABLE, JOB_NOT_FOUND, PROVIDER_UNAVAILABLE, CHECKOUT_NOT_READY