مستندات API پی جینگو

کلید را از داشبورد بگیرید، یکی از نمونه ها را اجرا کنید.

from openai import [OI]

client = [OI](
    base_url="https://payjingo.com/api/v1",
    api_key="sk-payjingo-...",
)

resp = client.chat.completions.create(
    model="",
    messages=[{"role": "user", "content": "سلام! خودت را معرفی کن."}],
)
print(resp.choices[0].message.content)
print(resp.usage)  # توکن های مصرفی

کلید را در هدر Authorization بفرستید؛ هرگز آن را در کد سمت کلاینت قرار ندهید.

• هدر Authorization: Bearer sk-payjingo-....
• کلید فقط یک بار هنگام ساخت نمایش داده می شود؛ آن را در متغیر محیطی نگه دارید.
• هر کلید می تواند بودجه ماهانه، تاریخ انقضا، سقف RPM/TPM و لیست مدل های مجاز داشته باشد.
• هزینه از کیف پول حساب شما کسر می شود؛ پیش از هر درخواست موجودی رزرو و بعد از پاسخ بر اساس usage واقعی تسویه می شود.

همه مسیرها زیر base_url قرار می گیرند.

با stream: true پاسخ به صورت SSE می آید و در chunk آخر usage گزارش می شود.

data: {"id":"chatcmpl-...","choices":[{"delta":{"content":"سلام"}}]}
data: {"id":"chatcmpl-...","choices":[],"usage":{"prompt_tokens":21,"completion_tokens":48,"total_tokens":69,
  "prompt_tokens_details":{"cached_tokens":0},"completion_tokens_details":{"reasoning_tokens":0}}}
data: [DONE]

توکن های reasoning مدل های استدلالی به عنوان خروجی محاسبه می شوند. توکن های cached با تعرفه کش (معمولاً ارزان تر) حساب می شوند.

قیمت هر مدل به تومان و به ازای یک میلیون توکن است و در صفحه قیمت ها قابل مشاهده است.

{
  "id": "",
  "vendor": "anthropic",
  "context_window": 200000,
  "max_output_tokens": 64000,
  "capabilities": ["streaming","tools","vision","cache","json_mode","reasoning"],
  "pricing": { "unit": "per_million_tokens", "currency": "IRT",
               "input": 17201, "output": 68804, "cache_read": 17201 }
}

سقف ها در سطح کلید تعریف می شوند و از داشبورد قابل تغییرند.

• محدودیت پیش فرض هر کلید بر اساس RPM و TPM است؛ عبور از آن 429 PJ_RATE_LIMITED برمی گرداند.
• حداکثر زمان انتظار برای پاسخ مدل ۱۲۰ ثانیه است؛ برای خروجی های طولانی از stream استفاده کنید.
• خطاهای موقت بالادست (503) به طور خودکار تا ۲ بار با backoff تلاش مجدد می شوند.
• هر مدل روی هر ارائه دهنده یک circuit breaker دارد: اگر در ۶۰ ثانیه ۵ خطای 5xx رخ دهد، مسیر ۳۰ ثانیه بسته می شود و درخواست ها به ارائه دهنده جایگزین همان مدل (failover) هدایت می شوند. قیمت همان قیمت مدل درخواستی است. اگر هیچ مسیری در دسترس نباشد 503 PJ_MODEL_UNAVAILABLE با هدر Retry-After برمی گردد.

برای درخواست های non-stream، تکرار ایمن بدون شارژ مجدد.

• هدر Idempotency-Key (۱ تا ۲۵۵ کاراکتر، مثلاً UUID) را به /chat/completions بفرستید.
• اگر پاسخ 2xx قبلاً برای همین کلید ذخیره شده باشد، تا ۲۴ ساعت همان پاسخ بدون تماس با مدل و بدون کسر هزینه برمی گردد؛ هدرهای Idempotent-Replayed: true و X-Original-Request-ID اضافه می شوند.
• درخواست هم زمان با همان کلید → 409 idempotency_in_progress؛ همان کلید با بدنه متفاوت → 422 idempotency_key_reused؛ کلید خالی یا بلندتر از ۲۵۵ کاراکتر → 400 invalid_idempotency_key.
• پاسخ های خطا ذخیره نمی شوند؛ پس تلاش مجدد با همان کلید بعد از خطا مجاز است. در حالت stream: true این هدر نادیده گرفته می شود.

curl https://payjingo.com/api/v1/chat/completions \
  -H "Authorization: Bearer $PAYJINGO_API_KEY" \
  -H "Idempotency-Key: 5f1c2e9a-7b3d-4c1e-9a2f-0d8e6b4a1c33" \
  -H "Content-Type: application/json" \
  -d '{"model":"","messages":[{"role":"user","content":"سلام"}]}'

همه خطاها با ساختار { error: { message, type, code, param, request_id } } برمی گردند.

در هر ابزار سازگار با [OI] فقط base URL و کلید را جایگزین کنید.