الوثائقواجهة HTTP6 دقيقة قراءة

واجهة HTTP

أربعة مسارات، JSON داخل وخارج. وكلُّ حزمة غلافٌ رفيع فوق هذه الواجهة؛ فأي شيء لا توفره حزمة جاهزة لمنصّتك تنجزه أنت عليها.

POST /v1/translate: نص واحد — وهو أكثر ما ستناديه.
POST /v1/translate/batch: حتى عشرين نصًّا، بلغة واحدة أو بثماني لغات، والجواب بالترتيب.
GET /v1/strings?target=ar: المشروع كاملًا في خريطة، بالنص الأصلي أو باسمك أنت.
GET /v1/languages: ما ضبطته المشروع من لغات.
GET /health: بلا مفتاح. يذكر أي الخدمات موصولة، ولا يفصح عن أي سر.

curl

# $SIYAK_HOST is the host printed on your project's API keys screen.
curl -s "$SIYAK_HOST/v1/translate" \
  -H "authorization: Bearer $SIYAK_KEY" \
  -H "content-type: application/json" \
  -d '{"text":"Your card expires soon","target":"ar","context":"screen:checkout"}'

# → {"text":"بطاقتك تنتهي قريبًا","origin":"model","status":"pending",
#    "chars":20,"badge":"Translated with Siyak",
#    "usage":{"used":1320,"limit":15000,"month":"2026-10"}}

يعمل أيضًا الترويسة البديلة x-siyak-key، ولا يتغيّر في الطلب شيءٌ آخر.

حقول الطلب

الحقل	مطلوب	ملاحظات
`text`	نعم	من 1 إلى 500 حرفًا بعد التنقية: تُحذف محارف التحكّم وتُقصّ المسافات من الطرفين. والأطول من ذلك يُجاب 400 لا اقتطاعًا.
`target`	نعم	وسم BCP-47 مثل ar وar-EG وzh-Hans. ويُخزَّن بصيغة واحدة: AR-eg تصير ar-EG، والاسمان لنصٍّ واحد.
`targets[]`	في الدفعة	حتى ثمانية بدائل عن target الواحد. وكل لغة تُحاسَب على أحرفها.
`source`	لا	يرجع إلى لغة المصدر المضبوطة على المشروع.
`context`	لا	حتى 160 حرفًا بلا < ولا >. جزء من هوية النص المخزّنة — راجع «كيف يُحسم النص».
`key`	لا	اسمك أنت للنص مثل checkout.title. منقّط وحتى 80 حرفًا. اختياري، والترجمة لا تنتظره.
`items[]`	في الدفعة	من 1 إلى 20 عنصرًا {text, context?, key?}. واللغة المضبوطة تسري على الجميع.

حقول الجواب

الحقل	المعنى
`text`	الترجمة.
`target`	اللغة التي طلبتها بتهجيتها المعيارية. فقارن هذه لا ما أرسلته.
`origin`	cache أو approved أو pending أو model: من أين جاء الجواب.
`status`	approved أو pending أو rejected: هل اعتمده أحد أم لا.
`chars`	ما حوسبت عليه هذه الدعوة، إن حوسبت.
`badge`	يظهر حين يجب الإسناد؛ اعرضه، فالباقة المجانية تُدفَع به.
`usage`	{used, limit, month}: عدّاد أحرف المشروع.
`results`	في دفعات targets[] فقط: {الوسم: {output, origin, status}} بند لكل لغة، والأوسمة معيارية.
`glossary_drift`	يظهر عندما يجيب النموذج بخلاف مصطلح مثبّت.

دلالات الدفعة

تطابق النتائج بالفهرس لا بالنص المُعاد، فالخادم ينقّي قبل الإعادة، وقد لا يكون ما أرسلته هو ما يرجع نصًّا.
والسطر بلا مخرج يحمل خطأه، ويظلّ المظروف 200.
وإن فني الرصيد في منتصف الدفعة توقّف الخادم عندها: أقلّ من عددك معناه أنه لم يحاول الباقي، فتبقى النصوص بلا ترجمة أولى من أن تُخصم.
ومع targets[] تنتقل الإجابات إلى results ومفاتيحها الأوسمة المعيارية، وتقول لك مصفوفة targets في الجواب أي تهجئة استُعملت. ويبقى output كما هو بلا قيمة حتى لا يتبدّل شكل السطر حسب الطلب.

رموز الحالة

الحالة	الخطأ	ما يُفعل
`400`	`invalid_request`	نص طويل أو وسم خاطئ أو سياق بأقواس. أصلح الاستدعاء فهو حتمي.
`401`	`invalid_api_key`	مفتاح ملغى أو مشروع معطّل أو بيئة خاطئة أو خطأ كتابة، وهي متماثلة عمدًا فلا تُستعمل نقطة النهاية لكشف المفاتيح.
`402`	`quota_exceeded`	انتهى رصيد الشهر، وفي الجواب usage. توقف وأخبر المطور، ولا أعد المحاولة في حلقة تكرار.
`403`	`origin_not_allowed`	نطاق متصفحك ليس في قائمة نطاقات المشروع. أضفه من لوحة التحكم.
`404`	`not_found`	مسار خاطئ. كل شيء تحت /v1.
`409`	`key_conflict`	اسمك الذي أرسلته يطلق نصًّا آخر في هذه اللغة. فلم يُخزَّن شيء ولم تُحسب أحرف؛ غيّر الاسم أو احذفه فيعود الاستدعاء ترجمة عادية.
`429`	`rate_limited`	راعِ retry_after؛ فالحد لكل مفتاح في الدقيقة.
`503`	`backend_unavailable`	النموذج معطَّل. ومع ذلك سُجِّل النص في صندوق الوارد ليراجعه أحد يدويًا؛ فاعرض نصّك الأصلي وتابع.
`500`	`internal_error`	الخطأ منّا، والرسالة فارغة عن قصد؛ افتح تذكرة وأرفق فيها الشهر والمشروع.