توثيق المطوّرين

أدلة التكامل مع الواجهة. القائمة الكاملة لنقاط النهاية في مرجع API.

بداية سريعة

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

اعرض النماذج المتاحة لمفتاحك ثم أرسل طلبك الأول.

bash

export API_KEY=sk_live_...
curl https://gapze.ir/v1/models -H "Authorization: Bearer $API_KEY"

curl https://gapze.ir/v1/responses \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"MODEL_SLUG","input":"Write a haiku about Tehran"}'

المصادقة

أرسل المفتاح في ترويسة Authorization كرمز Bearer (أو في X-API-Key). تتلقى الطلبات دون مفتاح صالح الرمز 401، والمفاتيح دون النطاق المطلوب الرمز 403.

http

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
# or
X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxx

التدفق

عيّن "stream": true لتلقي أحداث يرسلها الخادم. يحمل كل حدث جزءًا من الإجابة وينتهي التدفق بـ [DONE]. يمكن استئناف التوليد الذي بدأ عبر /v1/generations باستخدام Last-Event-ID.

bash

curl -N https://gapze.ir/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"model":"MODEL_SLUG","stream":true,"messages":[{"role":"user","content":"Hi"}]}'

# data: {"choices":[{"delta":{"content":"Hel"}}]}
# ...
# data: [DONE]

الأخطاء

تستخدم الأخطاء صيغة JSON واحدة: رمز ثابت مقروء آليًا، ورسالة مفهومة، والنوع، وهل تفيد إعادة المحاولة، ومعرّف الطلب. اذكر معرّف الطلب عند التواصل مع الدعم.

402 يعني أن الرصيد أو الميزانية غير كافيين؛ 409 تعارض في الحالة؛ 422 إدخال غير صالح؛ 429 حد المعدّل؛ 5xx خلل مؤقت.

json

{
  "error": {
    "code": "insufficient_budget",
    "message": "your balance is not enough for this request",
    "type": "billing_error",
    "retryable": false,
    "request_id": "req_01..."
  }
}

حدود المعدّل

تُطبَّق الحدود لكل مفتاح ولكل مشروع. تتضمن الاستجابة 429 الترويسة Retry-After بالثواني؛ انتظر هذه المدة على الأقل قبل الإعادة، ويُفضّل التراجع الأسي مع عشوائية.

http

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 6000

عدم التكرار

أرسل ترويسة Idempotency-Key فريدة مع الطلبات التي تُنشئ شيئًا أو تفرض رسومًا. الإعادة بالمفتاح نفسه تُرجع النتيجة الأصلية ولا تُحتسب مرتين أبدًا.

bash

curl https://gapze.ir/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: 3f1c2a6e-8b9d-4c1f-9e2a-7d5b6c4a3f21" ...

الرصيد وعروض الأسعار والاستخدام

يُخصم الاستخدام من محفظة مالك المفتاح. اطلب عرض سعر ملزمًا قبل المهام المكلفة، واقرأ رصيدك واستخدامك في أي وقت.

bash

curl https://gapze.ir/v1/balance -H "Authorization: Bearer $API_KEY"
curl "https://gapze.ir/v1/usage?from=2026-10-01" -H "Authorization: Bearer $API_KEY"
curl https://gapze.ir/v1/generations/quotes -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" -d '{"model":"MODEL_SLUG","messages":[...]}'

الملفات

ارفع الملفات لاستخدامها كمدخلات. تُرفع الملفات الصغيرة بطلب multipart واحد والكبيرة برفع قابل للاستئناف على أجزاء.

bash

curl https://gapze.ir/v1/files -H "Authorization: Bearer $API_KEY" \
  -F purpose=assistants -F file=@report.pdf
# large files: POST /v1/files/uploads → PUT /v1/files/uploads/{id}/parts/{n} → POST .../complete

المهام الطويلة

تُرجع مهام الفيديو والمهام الطويلة الأخرى معرّف المهمة فورًا. استعلم عن المهمة أو اشترك في Webhook job.completed ثم نزّل النتيجة.

bash

curl https://gapze.ir/v1/videos/generations -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" -d '{"model":"VIDEO_MODEL","prompt":"..."}'
# → {"id":"job_...","status":"queued"}
curl https://gapze.ir/v1/jobs/job_... -H "Authorization: Bearer $API_KEY"
curl -L https://gapze.ir/v1/jobs/job_.../content -H "Authorization: Bearer $API_KEY" -o out.mp4

Webhooks

يحمل كل تسليم الترويسات webhook-id وwebhook-timestamp وwebhook-signature. تحقّق من توقيع HMAC-SHA256 على «id.timestamp.body» بسرّ التوقيع، وارفض الطوابع الزمنية القديمة وأزل التكرار حسب المعرّف. أثناء تدوير السر يُرسل التوقيعان القديم والجديد.

python

import base64, hashlib, hmac, time

def verify(secret: str, headers: dict, body: bytes, tolerance=300) -> bool:
    msg_id, ts = headers["webhook-id"], headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > tolerance:
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    mac = hmac.new(key, f"{msg_id}.{ts}.".encode() + body, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(mac).decode()
    return any(hmac.compare_digest(expected, s) for s in headers["webhook-signature"].split())

الوضع التجريبي

لا تصل المفاتيح التجريبية إلا إلى المحاكي المدمج وتستهلك رصيدًا تجريبيًا. انتقل إلى مفتاح حقيقي عندما تكون جاهزًا.

bash

# test keys (sk_test_...) use the built-in simulator and test credits only
curl https://gapze.ir/v1/chat/completions -H "Authorization: Bearer sk_test_..." ...

مرجع API