واجهة التسليم — IngevoraMirage

واجهة التسليمتخبر واجهة التسليم (delivery API) خادمك بالإصدار المنشور الذي يجب تنزيله من عدسة الوجه أو تأثير الشاشة، وبمكان ملفاته. وتضم أربعة مسارات للقراءة فقط، جميعها على https://mirage-api.ingevora.com.المصادقةأرسل مفتاح API في الترويسة X-Api-Key مع كل طلب. ولا تقبل واجهة التسليم أي وسيلة أخرى. راجع مفاتيح API.المسارات

المسار

يجيب بـ

GET /v1/lenses/:lensId

أحدث إصدار منشور من عدسة الوجه

GET /v1/lenses/:lensId/versions/:version

إصدار مثبّت واحد من عدسة الوجه

GET /v1/effects/:effectId

أحدث إصدار منشور من تأثير الشاشة

GET /v1/effects/:effectId/versions/:version

إصدار مثبّت واحد من تأثير الشاشة

المعرّفات من نوع UUID؛ انسخها من صفحة Developers (المطوّرون) في المحرّر. ورقم الإصدار عدد صحيح يبدأ من 1. ويعمل المفتاح الواحد مع المنتجين كليهما.

bash

# The latest version of a face lens
curl -H "X-Api-Key: mk_…" https://mirage-api.ingevora.com/v1/lenses/8f3c2a10-…

# Version 2 of a screen effect
curl -H "X-Api-Key: mk_…" https://mirage-api.ingevora.com/v1/effects/5d1e7b42-…/versions/2

إجابة عدسة الوجه

json

{
  "data": {
    "lensId": "8f3c2a10-…",
    "version": 3,
    "manifestUrl": "https://…/lenses/8f3c2a10-…/3/manifest.json",
    "manifestSha256": "9f2c…",
    "totalBytes": 184522,
    "minEngineVersion": 1,
    "publishedAt": "2026-10-02T09:30:00.000Z",
    "previewUrl": "https://…/lenses/8f3c2a10-…/3/preview.png"
  },
  "success": true
}

الحقل

النوع

المعنى

lensId

string

معرّف عدسة الوجه.

version

integer

رقم الإصدار، بدءًا من 1.

manifestUrl

string

مكان تنزيل ملف manifest.json لهذا الإصدار. وتوجد صوره في المجلد نفسه.

manifestSha256

string

بصمة SHA-256 لبايتات ملف البيان كما هي تمامًا، في صورة 64 حرفًا ست عشريًا صغيرًا.

totalBytes

integer

حجم ملف البيان مضافًا إليه أحجام جميع الصور التي يستخدمها.

minEngineVersion

integer

أدنى إصدار من محرك العرض يستطيع رسم هذا الإصدار.

publishedAt

string

وقت النشر، بصيغة ISO 8601 وبتوقيت UTC.

previewUrl

string or null

صورة معاينة PNG لا تتجاوز 512 × 512 بكسل، أو null إن لم توجد. والحقل موجود دائمًا. المعاينة ليست جزءًا من الحزمة ولا تشملها البصمات، فلا تعتمد عليها أبدًا.

إجابة تأثير الشاشة

json

{
  "data": {
    "effectId": "5d1e7b42-…",
    "version": 2,
    "manifestUrl": "https://…/effects/5d1e7b42-…/2/manifest.json",
    "manifestSha256": "41ad…",
    "totalBytes": 96310,
    "minEngineVersion": 1,
    "durationMs": 2000,
    "publishedAt": "2026-10-01T16:05:12.000Z"
  },
  "success": true
}

للحقول المعنى نفسه كما في عدسة الوجه، مع effectId بدلًا من lensId. ويمثّل durationMs مدة التأثير بالمللي ثانية. ولا يحتوي تأثير الشاشة على previewUrl.ما يُجاب عنه بـ 404تعطي جميع الحالات التالية الرمز 404 نفسه، "Lens not found" أو "Screen effect not found":

معرّف غير موجود؛

عنصر ينتمي إلى مساحة عمل أخرى؛

عنصر لم يُنشر قط؛

عنصر محذوف؛

في المسار المثبّت، رقم إصدار غير موجود.

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

401 "Missing or invalid API key" — الترويسة مفقودة، أو المفتاح غير معروف أو ملغى.

403 "Face lenses are not enabled for this tenant" أو "Screen effects are not enabled for this tenant" — هذا المنتج معطّل لمساحة عملك (كلمة "tenant" هي التسمية التي تطلقها الواجهة على مساحة العمل). وتبيّن صفحة Developers المنتجات المفعّلة.

400 — المعرّف ليس UUID، أو رقم الإصدار ليس عددًا صحيحًا بين 1 و2147483647.

تصل كل الأخطاء في الغلاف نفسه. راجع الأخطاء والحدود.الاحتسابيُحتسب كل طلب تسليم يتم بمفتاح صالح على ذلك المفتاح، لكل يوم بتوقيت UTC، أيًا كانت الإجابة: فالرمز 404 يُحتسب أيضًا. أما تنزيل ملف البيان والصور فليس طلب تسليم ولا يُحتسب. خزّن الإجابات مؤقتًا على خادمك بدلًا من الطلب عند كل تشغيل للتطبيق.قد تتّسع الإجاباتقد تظهر حقول جديدة في هذه الإجابات دون إصدار جديد من الواجهة (وكان previewUrl أحدها). اقرأ الإجابات بمرونة وتجاهل الحقول التي لا تعرفها. وأي إزالة لحقل أو تغيير فيه سيُعلن عنه مسبقًا. راجع التنزيل الآمن.يتوفر مرجع الواجهة التفاعلي على https://mirage-api.ingevora.com/docs.