توثيق API

واجهة REST عامة من imagetranslate.ai. تتم المصادقة عبر رمز Bearer، ثم تُرسَل الصورة بترميز base64 لاسترداد الصورة المترجمة.

ترجمة النص داخل الصورة مع الحفاظ على التخطيط الأصلي وإعادة رسمه في الصورة نفسها.

بدء سريع

إرسال الطلب الأول

curl -X POST https://api.imagetranslate.ai/translate/image \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "sourceLanguage": "ja",
    "targetLanguage": "en",
    "mode": "general",
    "translator": "Grok"
  }'

الحقل response.resultImage يحتوي على صورة PNG بترميز base64 مسبوقة بالبادئة data:image/png;base64, (وليس رابط HTTP). لعرضها في المتصفح مباشرة، استخدم <img src={response.resultImage} />. لحفظها كملف، احذف البادئة ثم فُكَّ ترميز base64.

المصادقة

أضف API key إلى رأس Authorization بصيغة Bearer مع كل طلب:

Authorization: Bearer YOUR_KEY

API key عبارة عن سلسلة عشوائية بطول 32 بايت مسبوقة بالبادئة sk_imagetranslate_. تعامل معها كما تتعامل مع كلمة المرور: احفظها في مدير أسرار على الخادم، ولا تُدرجها ضمن المستودع، ولا تكشفها في كود الواجهة الأمامية.

Idempotency

عند إعادة محاولة الطلب بعد انقطاع الشبكة، أرسل الرأس Idempotency-Key نفسه لتجنّب خصم الكريدت مرتين:

Idempotency-Key: <your-uuid>

أول استدعاء بمفتاح معيّن: يُعالَج كالمعتاد.
أي استدعاء لاحق بالمفتاح نفسه (ضمن API key واحد): يُرجع 409 Conflict مع recordId الأصلي. لا تستهلك إعادة المحاولة أي رصيد.
المفاتيح المختلفة تعني استدعاءات مختلفة.

أنشئ المفتاح من جهة العميل (UUIDv4 مناسب). من دونه، تستهلك كل إعادة محاولة رصيدًا جديدًا وتُشغّل Torii من جديد.

ترجمة الصورة

نقطة نهاية متزامنة تُرجع الصورة المترجمة بترميز base64 (مسبوقة بالبادئة data:image/png;base64,).

Base URL

https://api.imagetranslate.ai

جسم الطلب

الحقل	النوع	إلزامي	الوصف
`imageBase64`	string	نعم	الصورة بترميز base64. يقبل سلسلة base64 مجردة أو data URL كاملة (`data:image/png;base64,...`). الحجم الأقصى 20 ميغابايت بعد فك الترميز.
`sourceLanguage`	string	نعم	رمز لغة ISO، أو `auto` للكشف التلقائي. راجع رموز اللغات.
`targetLanguage`	string	نعم	رمز لغة ISO. راجع رموز اللغات.
`mode`	string	لا	نمط العرض. القيمة الافتراضية `general`. راجع قيم mode.
`translator`	string	لا	نموذج الترجمة المستخدم. القيمة الافتراضية `grok-4`. راجع نماذج translator.
`customPrompt`	string	لا	تعليمات إضافية تُمرَّر إلى النموذج. الحد الأقصى 1000 حرف.

الاستجابة

الحقل	النوع	الوصف
`success`	boolean	تأخذ القيمة `true` عند نجاح الترجمة.
`recordId`	string	معرّف فريد لسجل هذا الاستدعاء. أرفقه عند التواصل مع الدعم.
`resultImage`	string	الصورة المترجمة بترميز base64 مسبوقة بالبادئة `data:image/png;base64,` (وليست رابط HTTP). اعرضها مباشرة عبر `<img src={...} />`، أو احفظها كملف بحذف البادئة وفك ترميز base64.
`remainingCredit`	number	رصيد advanced credit المتبقي بعد هذا الاستدعاء.

أمثلة

curl -X POST https://api.imagetranslate.ai/translate/image \
  -H "Authorization: Bearer $IMAGETRANSLATE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "imageBase64": "YOUR_BASE64_IMAGE",
    "sourceLanguage": "ja",
    "targetLanguage": "en",
    "mode": "general",
    "translator": "Grok"
  }'

مثال على الاستجابة

{
  "success": true,
  "recordId": "Z3l4abc...",
  "resultImage": "data:image/png;base64,iVBORw0KGgoAAAANSU...",
  "remainingCredit": 9990
}

رموز الأخطاء

Status	المعنى
`400`	تنسيق الطلب غير صحيح، أو أن `imageBase64` ليس base64 صالحًا.
`401`	API key مفقود أو غير صالح. أنشئ مفتاحًا جديدًا من API Keys.
`402`	رصيد advanced credit غير كافٍ. أعد الشحن من صفحة الأسعار. لم يُخصم أي رصيد من هذا الاستدعاء.
`403`	الباقة الحالية لا تتضمن الوصول إلى API. يلزم الترقية إلى Professional أو ما فوق من صفحة الأسعار.
`409`	`Idempotency-Key` مُستخدم من قبل. يُرجَع `{ "error": "idempotency_replay", "recordId": "<id>" }`. لم يُخصم أي رصيد.
`413`	حجم الصورة يتجاوز 20 ميغابايت بعد فك ترميز base64. اضغط الصورة أو قلّل حجمها.
`422`	فشل التحقق من صحة جسم الطلب (حقل مفقود/غير صالح). يحتوي الجسم على مصفوفة `detail` مع موقع الخطأ.
`429`	تجاوزت حد المعدل لباقتك. لم يُخصم رصيد.
`500`	فشل في الترجمة. يُعاد الرصيد تلقائيًا.

شكل استجابة الخطأ

4xx / 500: { "detail": "<رسالة>" }
422: { "detail": [{ "loc": [...], "msg": "...", "type": "..." }] }
409: { "error": "idempotency_replay", "recordId": "<id>", "message": "..." }

حدود المعدل

عدد الطلبات لكل API key في الدقيقة، بحسب الباقة:

الباقة	الحد
Free	غير متاح
Starter	غير متاح
Professional	60 req/min
Enterprise	300 req/min

هل تحتاج إلى حد أعلى؟ تواصل عبر [email protected].

Code	اللغة	Code	اللغة
`auto`	الكشف التلقائي (لـ source فقط)	`pt`	البرتغالية
`en`	الإنجليزية	`ru`	الروسية
`zh`	الصينية	`ar`	العربية
`zh-cn`	الصينية المبسطة	`hi`	الهندية
`zh-tw`	الصينية التقليدية	`th`	التايلاندية
`ja`	اليابانية	`vi`	الفيتنامية
`ko`	الكورية	`id`	الإندونيسية
`es`	الإسبانية	`tr`	التركية
`fr`	الفرنسية	`it`	الإيطالية
`de`	الألمانية	`nl`	الهولندية

القائمة الكاملة — أكثر من 130 لغة مصنفة حسب المنطقة

شرق آسيا

Code	اللغة
`zh`	الصينية
`zh-cn`	الصينية المبسطة
`zh-tw`	الصينية التقليدية
`ja`	اليابانية
`ko`	الكورية
`mn`	المنغولية
`jv`	الجاوية
`su`	السوندية

جنوب شرق آسيا

Code	اللغة
`vi`	الفيتنامية
`th`	التايلاندية
`id`	الإندونيسية
`ms`	الملايو
`my`	البورمية
`km`	الخميرية
`lo`	اللاوية
`fil`	الفلبينية
`ceb`	السيبوانو
`ilo`	الإيلوكانو

جنوب آسيا

Code	اللغة	Code	اللغة
`hi`	الهندية	`ne`	النيبالية
`bn`	البنغالية	`si`	السنهالية
`ur`	الأردية	`as`	الأسامية
`ta`	التاميلية	`bho`	البوجبورية
`te`	التيلوغو	`dv`	الديفيهية
`ml`	الماليالامية	`doi`	الدوغرية
`gu`	الغوجاراتية	`gom`	الكونكانية
`kn`	الكانادية	`mai`	الميثيلية
`mr`	الماراثية	`lus`	الميزو
`or`	الأورية	`pa`	البنجابية
`sa`	السنسكريتية	`sd`	السندية

أفريقيا

Code	اللغة	Code	اللغة
`am`	الأمهرية	`kri`	الكريو
`sw`	السواحيلية	`ln`	اللينغالا
`ha`	الهوسا	`nso`	السوتو الشمالية
`yo`	اليوروبا	`om`	الأورومو
`zu`	الزولو	`st`	السيسوتو
`xh`	الكوسا	`sn`	الشونا
`af`	الأفريقانية	`ti`	التغرينية
`mg`	الملغاشية	`ts`	التسونغا
`so`	الصومالية	`ak`	التوي
`bm`	البامبارا	`ee`	الإيوي
`ny`	التشيشيوا	`lg`	اللوغندا
`ig`	الإيغبو	`rw`	الكينيارواندية

أوروبا

Code	اللغة	Code	اللغة
`fr`	الفرنسية	`lt`	الليتوانية
`de`	الألمانية	`lv`	اللاتفية
`es`	الإسبانية	`et`	الإستونية
`it`	الإيطالية	`is`	الآيسلندية
`ru`	الروسية	`sq`	الألبانية
`pl`	البولندية	`hy`	الأرمنية
`uk`	الأوكرانية	`az`	الأذرية
`nl`	الهولندية	`eu`	الباسكية
`pt`	البرتغالية	`be`	البيلاروسية
`el`	اليونانية	`bs`	البوسنية
`cs`	التشيكية	`ca`	الكتالانية
`hu`	المجرية	`co`	الكورسيكية
`sv`	السويدية	`fy`	الفريزية
`da`	الدنماركية	`gl`	الغاليسية
`fi`	الفنلندية	`ka`	الجورجية
`no`	النرويجية	`kk`	الكازاخية
`ro`	الرومانية	`ky`	القيرغيزية
`bg`	البلغارية	`lb`	اللوكسمبورغية
`hr`	الكرواتية	`mk`	المقدونية
`sk`	السلوفاكية	`mt`	المالطية
`sl`	السلوفينية	`sr`	الصربية
`tg`	الطاجيكية	`tt`	التترية
`tk`	التركمانية	`ug`	الأويغورية
`uz`	الأوزبكية

الشرق الأوسط

Code	اللغة
`ar`	العربية
`fa`	الفارسية
`tr`	التركية
`he`	العبرية
`ku`	الكردية
`ckb`	الكردية السورانية
`ps`	الباشتو

الأمريكتان وأوقيانوسيا

Code	اللغة
`ay`	الأيمارا
`gn`	الغوارانية
`ht`	الكريولية الهايتية
`haw`	الهاواي
`qu`	الكيتشوا
`sm`	الساموية
`mi`	الماورية

أخرى

Code	اللغة
`eo`	الإسبرانتو
`la`	اللاتينية
`cy`	الويلزية
`ga`	الأيرلندية
`gd`	الغيلية الإسكتلندية
`hmn`	الهمونغ
`yi`	اليديشية

قيم mode

يحدد mode نمط العرض. اختر النمط الأنسب لمحتوى صورتك.

Value	الوصف
`general` (الافتراضي)	الوضع الافتراضي بدون عرض خاص.
`manga`	الحفاظ على التخطيط الأصلي مع إضافة حد حول النص.
`e-commerce`	الحفاظ على التخطيط الأصلي بدون حد حول النص.
`light-novel`	وضع النص المترجم فوق الصورة الأصلية.

نماذج translator

يحدد translator نموذج الذكاء الاصطناعي الذي ينفذ الترجمة. تبلغ تكلفة كل نموذج 10 كريدت لكل استدعاء.

Grok (الافتراضي)
Gemini
Deepseek
ChatGPT
Claude

ابدأ الآن

هل أنت مستعد للدمج؟ أنشئ أول API key ←