پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

پرسش از هوش مصنوعی

پرسش از AvalAI پرسش از Claude پرسش از ChatGPT

هدرهای پاسخ

تمام پاسخ‌های AvalAI API شامل هدرهای HTTP استاندارد به علاوه هدرهای سفارشی هستند که اطلاعات مهمی درباره درخواست‌ها، محدودیت‌های نرخ و پیگیری هزینه ارائه می‌دهند.

فهرست مطالب

هدرهای پیگیری درخواست
خط زمانی مهاجرت
هدرهای متادیتای API
شناسه‌های درخواست سمت کلاینت
هدرهای محدودیت نرخ
هدرهای توکن در سطح پروژه
گردش‌کار retry مبتنی بر هدر
هدرهای HTTP استاندارد
مثال‌ها
بهترین شیوه‌ها

هدرهای پیگیری درخواست

`avalai-request-id`

مهم‌ترین هدر برای پیگیری هزینه و رفع اشکال.

هر پاسخ API شامل یک هدر یکتای avalai-request-id است که حاوی UUID شناسایی آن درخواست خاص است. این شناسه برای موارد زیر ضروری است:

پیگیری دقیق هزینه: از آن با /user/v1/transactions/lookup برای دریافت جزئیات دقیق هزینه استفاده کنید
رفع اشکال: هنگام گزارش مشکلات به پشتیبانی، به این شناسه مراجعه کنید
همبستگی درخواست: درخواست‌ها را در سیستم‌های خود پیگیری کنید
مسیر حسابرسی: سوابق فراخوانی‌های API را نگهداری کنید

فرمت: UUID v7 (مثلا 01a009d5-ec91-74c2-8ffa-9eba731dfc9e)

مثال:

avalai-request-id: 01a009d5-ec91-74c2-8ffa-9eba731dfc9e

اطلاعیه تغییر هدر: هدر avalai-request-id جایگزین هدر قدیمی x-request-id شده است. در یک پنجره انتقالی ۶۰ روزه هر دو هدر با مقدار یکسان برگردانده می‌شوند. برای جزئیات به خط زمانی مهاجرت و اطلاعیه انتشار مراجعه کنید.

x-request-id (قدیمی، منسوخ)

هدر x-request-id نام قدیمی شناسه درخواست AvalAI است. از آنجا که برخی CDNها نیز از x-request-id برای رهگیری داخلی خود استفاده می‌کنند و ممکن است این هدر را بازنویسی کنند، دیگر نمی‌توان آن را شناسه‌ای قطعی برای AvalAI دانست.

تا 2026-10-15 (۱۴۰۵-۰۷-۲۳): AvalAI هدر x-request-id را در کنار avalai-request-id با همان مقدار UUID برمی‌گرداند.
پس از 2026-10-15 (۱۴۰۵-۰۷-۲۳): AvalAI دیگر x-request-id را برنمی‌گرداند. هر x-request-id که پس از این تاریخ مشاهده کنید، توسط واسطی مانند CDN اضافه شده و شناسه درخواست AvalAI شما نیست.

برای lookup هزینه، trace پشتیبانی و log کردن، avalai-request-id را بخوانید. اگر در طول پنجره انتقالی به کد سازگار با قبل نیاز دارید، فقط در نبود avalai-request-id به x-request-id بازگشت (fallback) کنید:

python

request_id = response.headers.get("avalai-request-id") or response.headers.get(
    "x-request-id"
)

خط زمانی مهاجرت

چرا هدر تغییر کرد

برخی CDNهایی که جلوی originهای API قرار می‌گیرند، مقدار خود را در هدر x-request-id قرار می‌دهند و ممکن است این هدر را برای رهگیری داخلی خود بازنویسی یا دوباره استفاده کنند. وقتی درخواستی از چنین CDN عبور می‌کند، مقدار مشاهده‌شده ممکن است به‌جای درخواست AvalAI، ایستگاه (hop) مربوط به CDN را شناسایی کند. برای اینکه lookup هزینه و trace پشتیبانی قطعی بماند، AvalAI شناسه درخواست خود را در هدر اختصاصی avalai-request-id برمی‌گرداند.

پنجره انتقالی

فاز	تاریخ	هدرهای پاسخ
آغاز پنجره دوهدری	2026-08-16 (۱۴۰۵-۰۵-۲۵)	هر دو هدر `avalai-request-id` و `x-request-id` با همان مقدار UUID برگردانده می‌شوند
پایان پنجره دوهدری	2026-10-15 (۱۴۰۵-۰۷-۲۳)	آخرین روزی که AvalAI هدر `x-request-id` را برمی‌گرداند
بازنشستگی هدر قدیمی	پس از 2026-10-15 (۱۴۰۵-۰۷-۲۳)	فقط `avalai-request-id` توسط AvalAI برگردانده می‌شود

نمونه هدرهای پاسخ در طول پنجره انتقالی:

x-ratelimit-limit-requests: 1500
x-ratelimit-remaining-requests: 1499
x-ratelimit-limit-tokens: 30000000
x-ratelimit-remaining-tokens: 29999827
x-ratelimit-reset-requests: 50s
x-ratelimit-reset-tokens: 50s
x-request-id: 01a009d5-ec91-74c2-8ffa-9eba731dfc9e
avalai-request-id: 01a009d5-ec91-74c2-8ffa-9eba731dfc9e

اقدام لازم

تا پیش از 2026-10-15 (۱۴۰۵-۰۷-۲۳) هدرخوان‌های خود را به avalai-request-id به‌روزرسانی کنید. در طول پنجره، هر دو هدر به همان درخواست اشاره می‌کنند.
پس از این پنجره، دیگر x-request-id را parse، log یا برای billing استفاده نکنید؛ ممکن است متعلق به CDN باشد.
فیلدهای request_id داخل بدنه پاسخ (مثلا در Videos API) بدون تغییر می‌مانند؛ آن‌ها همان مقدار UUID هدر avalai-request-id را حمل می‌کنند و تحت تأثیر این تغییر نیستند.
هدر درخواست X-Client-Request-Id که در ادامه توضیح داده شده، نیازی به تغییر ندارد.

هدرهای متادیتای API

برخی routeهای سازگار با OpenAI می‌توانند هدرهای متادیتای بیشتری برگردانند. آن‌ها را diagnostic مفید بدانید، نه فیلدهای الزامی روی همه routeهای provider در AvalAI:

هدر	معنی	کاربرد
`openai-processing-ms`	زمان پردازش مدل در upstream بر حسب میلی‌ثانیه.	latency مربوط به provider/model را از زمان app، شبکه و queue جدا کنید.
`openai-version`	نسخه REST API استفاده‌شده توسط route سازگار با upstream.	هنگام migrationهای SDK یا API آن را log کنید تا تغییر رفتار راحت‌تر trace شود.
`openai-organization`	سازمان upstream مرتبط با درخواست، وقتی expose شده باشد.	فقط برای debugging استفاده کنید؛ برای authorization حساب AvalAI به آن وابسته نشوید.
`service_tier` یا metadata سطح پردازش	tier پردازشی که واقعا برای درخواست استفاده شده، وقتی route آن را برگرداند.	در بررسی latency، حالت پردازشی درخواستی و حالت serveشده را مقایسه کنید.

منطق billing را بر اساس این metadata headerها نسازید. برای billing AvalAI و reconciliation نمایندگان، مسیر authoritative همچنان avalai-request-id به‌همراه transaction lookup در User API است.

شناسه‌های درخواست سمت کلاینت

routeهای سازگار با OpenAI می‌توانند هدر درخواست X-Client-Request-Id را هم بپذیرند. از آن به‌عنوان trace ID داخلی خودتان استفاده کنید: برای هر تلاش API یک مقدار یکتا بسازید، همراه درخواست بفرستید و کنار avalai-request-id برگشتی log کنید.

این هدر وقتی مفید است که timeout یا خطای شبکه اجازه ندهد برنامه شما هدرهای پاسخ را دریافت کند. اگر route انتخابی AvalAI metadata سازگار با OpenAI را حفظ کند، پشتیبانی می‌تواند از client request ID شما به‌عنوان کلید دوم برای پیگیری استفاده کند. مقدار را فقط ASCII، حداکثر ۵۱۲ کاراکتر و یکتا برای هر درخواست نگه دارید. این هدر جایگزین avalai-request-id نیست؛ شناسه پاسخ AvalAI همچنان شناسه authoritative برای lookup هزینه و پشتیبانی است.

bash

curl https://api.avalai.ir/v1/responses \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "یک health check یک‌خطی برگردان."
  }'

دسترسی به `avalai-request-id` از طریق SDKها

هنگام استفاده از SDKهای رسمی مانند OpenAI Python SDK، از طریق raw-response API هدر را بگیرید تا کد شما مستقیما avalai-request-id را بخواند:

پایتون (OpenAI SDK)

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

raw_response = client.chat.completions.with_raw_response.create(
    model="gpt-5.4-mini",
    messages=[{"role": "user", "content": "سلام!"}],
)
completion = raw_response.parse()

# دسترسی به شناسه درخواست از هدرهای پاسخ
request_id = raw_response.headers.get("avalai-request-id")
print(f"شناسه درخواست: {request_id}")
# خروجی: شناسه درخواست: 01a009d5-ec91-74c2-8ffa-9eba731dfc9e

توجه

در طول پنجره انتقالی می‌توانید مقدار قدیمی را با raw_response.headers.get("x-request-id") هم بخوانید؛ هر دو به همان UUID اشاره می‌کنند. پس از 2026-10-15 (۱۴۰۵-۰۷-۲۳) فقط avalai-request-id برگردانده می‌شود؛ بنابراین پیش از این تاریخ همه هدرخوان‌ها را مهاجرت کنید و پس از پایان پنجره به attributeهای SDK که از نام قدیمی هدر مشتق شده‌اند اتکا نکنید.

نسخه معادل Responses API

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از response.output_text خوانده می‌شود.

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.4-mini",
    instructions="You are a helpful assistant.",
    input="سلام!",
)

print(response.output_text)

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

دسترسی به `avalai-request-id` با LangChain

LangChain به طور مستقیم هدرهای پاسخ HTTP خام را از فراخوانی‌های API زیرساختی نمایش نمی‌دهد. با این حال، می‌توانید هدر avalai-request-id را با استفاده از یک کلاینت HTTP سفارشی که هدرهای پاسخ را رهگیری می‌کند، ضبط کنید.

پایتون LangChain v0.3 (همزمان)

python

import httpx
from langchain_openai import ChatOpenAI
from langchain_core.callbacks import BaseCallbackHandler
from contextvars import ContextVar
import os

# ذخیره هدرها در متغیر context برای امنیت نخ
request_headers: ContextVar[dict] = ContextVar("request_headers", default={})


class HeaderCapturingClient(httpx.Client):
    def send(self, request, **kwargs):
        response = super().send(request, **kwargs)
        request_headers.set(dict(response.headers))
        return response


class HeaderAccessCallback(BaseCallbackHandler):
    def __init__(self):
        self.request_id = None

    def on_llm_end(self, response, **kwargs):
        headers = request_headers.get()
        self.request_id = headers.get("avalai-request-id")
        print(f"شناسه درخواست ضبط شده: {self.request_id}")


# راه‌اندازی
http_client = HeaderCapturingClient()
chat_generator = ChatOpenAI(
    base_url="https://api.avalai.ir/v1",
    api_key=os.getenv("AVALAI_API_KEY"),
    model="gpt-5.4-mini",
    http_client=http_client,
)

callback = HeaderAccessCallback()
response = chat_generator.invoke("بگو سلام", config={"callbacks": [callback]})

print(f"شناسه درخواست از callback: {callback.request_id}")

پایتون LangChain v0.3 (غیرهمزمان)

python

import httpx
from contextvars import ContextVar
from langchain_openai import ChatOpenAI
from langchain_core.callbacks import AsyncCallbackHandler
import os

request_headers: ContextVar[dict] = ContextVar("request_headers", default={})


class AsyncHeaderCapturingClient(httpx.AsyncClient):
    async def send(self, request, **kwargs):
        response = await super().send(request, **kwargs)
        request_headers.set(dict(response.headers))
        return response


class AsyncHeaderAccessCallback(AsyncCallbackHandler):
    def __init__(self):
        self.request_id = None

    async def on_llm_end(self, response, **kwargs):
        headers = request_headers.get()
        self.request_id = headers.get("avalai-request-id")
        print(f"شناسه درخواست ضبط شده: {self.request_id}")


# راه‌اندازی
http_client = AsyncHeaderCapturingClient()
chat_generator = ChatOpenAI(
    base_url="https://api.avalai.ir/v1",
    api_key=os.getenv("AVALAI_API_KEY"),
    model="gpt-5.4-mini",
    http_async_client=http_client,
)

# استفاده (در محیط غیرهمزمان اجرا کنید)
callback = AsyncHeaderAccessCallback()
response = await chat_generator.ainvoke("بگو سلام", config={"callbacks": [callback]})

نحوه کار: این روش از یک کلاینت httpx سفارشی استفاده می‌کند که هدرهای پاسخ را در یک متغیر context ضبط می‌کند. سپس callback مربوط به LangChain پس از تکمیل فراخوانی LLM به این هدرها دسترسی پیدا می‌کند. ContextVar امنیت نخ را هنگام ارسال درخواست‌های همزمان تضمین می‌کند. در طول پنجره انتقالی می‌توانید در نبود هدر جدید، به headers.get("x-request-id") بازگشت (fallback) کنید.

دسترسی از طریق هدرهای HTTP (سایر SDKها)

برای سایر SDKها یا درخواست‌های HTTP مستقیم، به هدر از پاسخ دسترسی پیدا کنید:

SDK/روش	نحوه دسترسی
پایتون (OpenAI)	`client.chat.completions.with_raw_response.create(...).headers.get("avalai-request-id")`
پایتون (requests)	`response.headers.get("avalai-request-id")`
جاوااسکریپت (OpenAI)	`(await ...create(...).withResponse()).response.headers.get("avalai-request-id")`
جاوااسکریپت (fetch)	`response.headers.get("avalai-request-id")`
Go (net/http)	`resp.Header.Get("avalai-request-id")`
PHP (curl)	استخراج با `preg_match('/avalai-request-id:\s*([^\r\n]+)/i', ...)`

برای نمایندگان فروش: این هدر برای کسب‌وکار شما حیاتی است. همیشه آن را ضبط و ذخیره کنید تا هزینه دقیق هر فراخوانی API را پیگیری کنید. نقطه پایانی /user/v1/transactions/lookup با استفاده از این شناسه، داده‌های هزینه ۱۰۰٪ دقیق را ظرف ۳۰ ثانیه برمی‌گرداند. برای گردش کار کامل به راهنمای پیگیری هزینه نمایندگان مراجعه کنید.

هدرهای محدودیت نرخ

AvalAI محدودیت نرخ را برای اطمینان از استفاده عادلانه و ثبات سیستم پیاده‌سازی می‌کند. هر پاسخ API شامل هدرهایی است که شما را از وضعیت فعلی محدودیت نرخ خود مطلع می‌کند.

محدودیت‌های نرخ بر اساس درخواست

هدر	توضیحات	مثال
`x-ratelimit-limit-requests`	حداکثر درخواست‌های مجاز در بازه زمانی	`30000`
`x-ratelimit-remaining-requests`	درخواست‌های باقی‌مانده در پنجره فعلی	`29999`
`x-ratelimit-reset-requests`	زمان تا بازنشانی محدودیت درخواست	`45s`

محدودیت‌های نرخ بر اساس توکن

هدر	توضیحات	مثال
`x-ratelimit-limit-tokens`	حداکثر توکن‌های مجاز در بازه زمانی	`150000000`
`x-ratelimit-remaining-tokens`	توکن‌های باقی‌مانده در پنجره فعلی	`149999982`
`x-ratelimit-reset-tokens`	زمان تا بازنشانی محدودیت توکن	`45s`

هدرهای توکن در سطح پروژه

برخی routeهای سازگار با upstream ممکن است وقتی bucket توکن در سطح پروژه اعمال می‌شود، هدرهای project-token برگردانند:

هدر	توضیحات	مثال
`x-ratelimit-limit-project-tokens`	بیشینه توکن‌های مجاز در سطح پروژه در پنجره فعلی	`60000`
`x-ratelimit-remaining-project-tokens`	توکن‌های باقی‌مانده در سطح پروژه پیش از throttling	`57000`
`x-ratelimit-reset-project-tokens`	زمان تا reset شدن bucket توکن سطح پروژه	`3s`

اگر این هدرها وجود دارند، آن‌ها را علاوه بر هدرهای request و token مانیتور کنید. ممکن است request به‌خاطر تمام شدن bucket پروژه throttle شود، حتی وقتی bucket توکن route هنوز ظرفیت دارد.

سطوح محدودیت نرخ

محدودیت‌های نرخ شما به سطح حساب کاربری شما (۰-۵) بستگی دارد. سطوح بالاتر محدودیت‌های بالاتری دارند. برای اطلاعات تفصیلی سطح به راهنمای محدودیت نرخ مراجعه کنید.

۴۲۹ درخواست‌های بیش از حد

اگر از محدودیت‌های نرخ خود فراتر روید، یک کد وضعیت 429 با یک هدر Retry-After دریافت خواهید کرد که نشان می‌دهد چه زمانی می‌توانید دوباره امتحان کنید:

HTTP/2 429
Retry-After: 45
x-ratelimit-limit-requests: 30000
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 45s

گردش‌کار retry مبتنی بر هدر

برای قابل‌پیش‌بینی کردن retryها، به‌جای تلاش کورکورانه از هدرهای پاسخ استفاده کنید:

ابتدا avalai-request-id را ذخیره کنید. قبل از parse کردن body آن را log کنید تا پشتیبانی، lookup هزینه نمایندگان و trace داخلی به همان درخواست اشاره کنند.
در خطای ۴۲۹ به Retry-After احترام بگذارید. به اندازه همان مقدار صبر کنید؛ اگر وجود نداشت، از exponential backoff همراه jitter و حداکثر تعداد retry استفاده کنید.
همه bucketها را بررسی کنید. یک درخواست ممکن است به‌خاطر محدودیت request، محدودیت token یا محدودیت token در سطح پروژه متوقف شود؛ بنابراین x-ratelimit-remaining-requests، x-ratelimit-remaining-tokens و هر هدر x-ratelimit-remaining-project-tokens را مانیتور کنید.
فشار token را کم کنید. اگر هدرهای token گلوگاه هستند، max_tokens را کاهش دهید، promptها را کوتاه کنید، نوبت‌های قبلی را خلاصه کنید یا کارهای bulk غیر فوری را به workflowهای batch منتقل کنید.
Graceful failure داشته باشید. وقتی retryها تمام شدند، پیام روشن «بعدا دوباره تلاش کنید» به کاربر بدهید و avalai-request-id ذخیره‌شده را در log نگه دارید.

هدرهای HTTP استاندارد

Content-Type

نوع رسانه بدنه پاسخ را نشان می‌دهد:

Content-Type: application/json

Content-Length

اندازه بدنه پاسخ به بایت:

Content-Length: 970

Date

زمان سرور هنگام تولید پاسخ:

Date: Thu, 27 Nov 2025 09:24:15 GMT

مثال‌ها

مثال کامل هدرهای پاسخ

در اینجا یک مثال کامل از هدرهای رایج یک درخواست معمولی API آمده است. برخی metadata headerهای سازگار با upstream وابسته به route هستند و ممکن است وجود نداشته باشند. در طول پنجره انتقالی هر دو هدر شناسه درخواست وجود دارند:

bash

# از پرچم -i برای نمایش هدرها استفاده کنید
curl -i "https://api.avalai.ir/v1/chat/completions" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role": "user", "content": "سلام"}]
  }'

# هدرهای پاسخ:
# HTTP/2 200
# date: Thu, 27 Nov 2025 09:24:15 GMT
# content-type: application/json
# content-length: 970
# openai-processing-ms: 842
# openai-version: 2020-10-01
# x-ratelimit-limit-requests: 30000
# x-ratelimit-remaining-requests: 29999
# x-ratelimit-limit-tokens: 150000000
# x-ratelimit-remaining-tokens: 149999982
# x-ratelimit-reset-requests: 45s
# x-ratelimit-reset-tokens: 45s
# x-ratelimit-remaining-project-tokens: 57000
# x-request-id: 01a009d5-ec91-74c2-8ffa-9eba731dfc9e
# avalai-request-id: 01a009d5-ec91-74c2-8ffa-9eba731dfc9e

python

# مثال پایتون - دسترسی به هدرهای پاسخ
import requests

response = requests.post(
    "https://api.avalai.ir/v1/chat/completions",
    headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
    json={"model": "gpt-5.4-mini", "messages": [{"role": "user", "content": "سلام"}]},
)

# دسترسی به هدرها
request_id = response.headers.get("avalai-request-id")
remaining_requests = response.headers.get("x-ratelimit-remaining-requests")
remaining_tokens = response.headers.get("x-ratelimit-remaining-tokens")
reset_time = response.headers.get("x-ratelimit-reset-requests")

print(f"شناسه درخواست: {request_id}")
print(f"درخواست‌های باقی‌مانده: {remaining_requests}")
print(f"توکن‌های باقی‌مانده: {remaining_tokens}")
print(f"زمان بازنشانی: {reset_time}")

javascript

// مثال جاوااسکریپت - دسترسی به هدرهای پاسخ
const response = await fetch("https://api.avalai.ir/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AVALAI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-5.4-mini",
    messages: [{ role: "user", content: "سلام" }],
  }),
});

// دسترسی به هدرها
const requestId = response.headers.get("avalai-request-id");
const remainingRequests = response.headers.get("x-ratelimit-remaining-requests");
const remainingTokens = response.headers.get("x-ratelimit-remaining-tokens");
const resetTime = response.headers.get("x-ratelimit-reset-requests");

console.log(`شناسه درخواست: ${requestId}`);
console.log(`درخواست‌های باقی‌مانده: ${remainingRequests}`);
console.log(`توکن‌های باقی‌مانده: ${remainingTokens}`);
console.log(`زمان بازنشانی: ${resetTime}`);

go

// مثال Go - دسترسی به هدرهای پاسخ
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]interface{}{
		"model":    "gpt-5.4-mini",
		"messages": []map[string]string{{"role": "user", "content": "سلام"}},
	})

	req, _ := http.NewRequest("POST", "https://api.avalai.ir/v1/chat/completions", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AVALAI_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, _ := (&http.Client{}).Do(req)
	defer resp.Body.Close()

	// دسترسی به هدرها
	requestID := resp.Header.Get("avalai-request-id")
	remainingRequests := resp.Header.Get("x-ratelimit-remaining-requests")
	remainingTokens := resp.Header.Get("x-ratelimit-remaining-tokens")
	resetTime := resp.Header.Get("x-ratelimit-reset-requests")

	fmt.Printf("شناسه درخواست: %s\n", requestID)
	fmt.Printf("درخواست‌های باقی‌مانده: %s\n", remainingRequests)
	fmt.Printf("توکن‌های باقی‌مانده: %s\n", remainingTokens)
	fmt.Printf("زمان بازنشانی: %s\n", resetTime)
}

php

<?php
// مثال PHP - دسترسی به هدرهای پاسخ
$ch = curl_init('https://api.avalai.ir/v1/chat/completions');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . getenv('AVALAI_API_KEY'),
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'model' => 'gpt-5.4-mini',
    'messages' => [['role' => 'user', 'content' => 'سلام']]
]));

$response = curl_exec($ch);
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers = substr($response, 0, $headerSize);
$body = substr($response, $headerSize);
curl_close($ch);

// تجزیه هدرها
preg_match('/avalai-request-id:\s*([^\r\n]+)/i', $headers, $requestId);
preg_match('/x-ratelimit-remaining-requests:\s*([^\r\n]+)/i', $headers, $remainingRequests);
preg_match('/x-ratelimit-remaining-tokens:\s*([^\r\n]+)/i', $headers, $remainingTokens);
preg_match('/x-ratelimit-reset-requests:\s*([^\r\n]+)/i', $headers, $resetTime);

echo "شناسه درخواست: " . trim($requestId[1] ?? '') . "\n";
echo "درخواست‌های باقی‌مانده: " . trim($remainingRequests[1] ?? '') . "\n";
echo "توکن‌های باقی‌مانده: " . trim($remainingTokens[1] ?? '') . "\n";
echo "زمان بازنشانی: " . trim($resetTime[1] ?? '') . "\n";
?>

نسخه معادل Responses API

وقتی مدل انتخابی از /v1/responses پشتیبانی می‌کند، این نسخه را کنار مثال Chat Completions استفاده کنید. messages به input منتقل می‌شود و متن نهایی از response.output_text خوانده می‌شود.

PythonJavaScriptBash

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AVALAI_API_KEY"],
    base_url="https://api.avalai.ir/v1",
)

response = client.responses.create(
    model="gpt-5.4-mini",
    instructions="You are a helpful assistant.",
    input="سلام",
)

print(response.output_text)

javascript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const response = await client.responses.create({
  model: "gpt-5.4-mini",
  instructions: "You are a helpful assistant.",
  input: "سلام",
});

console.log(response.output_text);

bash

curl https://api.avalai.ir/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '
  {
    "model": "gpt-5.4-mini",
    "input": "سلام",
    "instructions": "You are a helpful assistant."
  }'

messages → input
پیام سیستمی → instructions یا آیتم developer
choices[0].message.content → response.output_text
برای ابزارها و خروجی‌های چندوجهی، response.output را بر اساس type بررسی کنید.

بهترین شیوه‌ها

۱. همیشه `avalai-request-id` را ضبط کنید

avalai-request-id را از هر فراخوانی API ذخیره کنید برای:

پیگیری هزینه و صورتحساب (به ویژه برای نمایندگان فروش)
رفع اشکال و درخواست‌های پشتیبانی
مسیرهای حسابرسی و انطباق

در طول پنجره انتقالی (تا 2026-10-15 (۱۴۰۵-۰۷-۲۳)) می‌توانید در نبود هدر جدید به x-request-id بازگشت (fallback) کنید، اما پیش از پایان پنجره این fallback را حذف کنید. اگر X-Client-Request-Id هم می‌فرستید، هر دو شناسه را کنار هم log کنید تا گزارش timeoutها و پاسخ‌های موفق قابل correlate باشند.

python

# شیوه خوب
request_id = response.headers.get("avalai-request-id")
db.store_request_log(user_id=user.id, request_id=request_id, timestamp=now())

۲. محدودیت‌های نرخ را به صورت فعال نظارت کنید

منتظر خطاهای ۴۲۹ نباشید. هدرهای محدودیت نرخ خود را نظارت کرده و استراتژی‌های عقب‌نشینی پیاده‌سازی کنید:

python

remaining = int(response.headers.get("x-ratelimit-remaining-requests", 0))
if remaining < 100:  # کمتر از ۱۰۰ درخواست باقی‌مانده
    time.sleep(1)  # عقب‌نشینی

۳. پاسخ‌های ۴۲۹ را به خوبی مدیریت کنید

عقب‌نشینی نمایی را هنگام دریافت خطاهای محدودیت نرخ پیاده‌سازی کنید:

python

import time


def make_request_with_retry(max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(...)

        if response.status_code == 429:
            retry_after = int(response.headers.get("retry-after", 60))
            time.sleep(retry_after)
            continue

        return response

    raise Exception("حداکثر تلاش‌های مجدد فراتر رفت")

۴. از شناسه‌های درخواست برای جستجوی هزینه استفاده کنید

برای پیگیری دقیق هزینه، تا ۳۰ ثانیه پس از درخواست صبر کنید، سپس از User API پرس‌وجو کنید:

python

# مرحله ۱: فراخوانی API و ضبط avalai-request-id
response = requests.post(...)
request_id = response.headers.get("avalai-request-id")

# مرحله ۲: صبر برای پردازش
time.sleep(5)  # معمولا خیلی زودتر در دسترس است

# مرحله ۳: دریافت هزینه دقیق
cost_data = requests.post(
    "https://api.avalai.ir/user/v1/transactions/lookup",
    json={"transaction_ids": [request_id]},
)

برای گردش کار کامل به راهنمای پیگیری هزینه نمایندگان مراجعه کنید.

۵. هدرها را برای رفع اشکال ثبت کنید

هنگام گزارش مشکلات به پشتیبانی، هدرهای مرتبط را شامل کنید:

python

import logging

logging.info(f"شناسه درخواست: {response.headers.get('avalai-request-id')}")
logging.info(f"کد وضعیت: {response.status_code}")
logging.info(f"محدودیت نرخ: {response.headers.get('x-ratelimit-remaining-requests')}")

منابع مرتبط

اطلاعیه مهاجرت هدر شناسه درخواست - جایگزینی x-request-id با avalai-request-id
مرجع User API - پیگیری استفاده و هزینه‌ها با استفاده از شناسه‌های درخواست
راهنمای محدودیت نرخ - درک سطوح محدودیت نرخ و بهترین شیوه‌ها
راهنمای پیگیری هزینه نمایندگان - راهنمای گام به گام برای پیگیری دقیق هزینه
مدیریت خطا - بهترین شیوه‌ها برای مدیریت خطاهای API
API تکمیل گفتگو - مستندات نقطه پایانی اصلی API

هدرهای پاسخ ​

فهرست مطالب ​

هدرهای پیگیری درخواست ​

avalai-request-id ​

x-request-id (قدیمی، منسوخ) ​

خط زمانی مهاجرت ​

چرا هدر تغییر کرد ​

پنجره انتقالی ​

اقدام لازم ​

هدرهای متادیتای API ​

شناسه‌های درخواست سمت کلاینت ​

دسترسی به avalai-request-id از طریق SDKها ​

دسترسی به avalai-request-id با LangChain ​

هدرهای محدودیت نرخ ​

محدودیت‌های نرخ بر اساس درخواست ​

محدودیت‌های نرخ بر اساس توکن ​

هدرهای توکن در سطح پروژه ​

سطوح محدودیت نرخ ​

گردش‌کار retry مبتنی بر هدر ​

هدرهای HTTP استاندارد ​

Content-Type ​

Content-Length ​

Date ​

مثال‌ها ​

مثال کامل هدرهای پاسخ ​

بهترین شیوه‌ها ​

۱. همیشه avalai-request-id را ضبط کنید ​

۲. محدودیت‌های نرخ را به صورت فعال نظارت کنید ​

۳. پاسخ‌های ۴۲۹ را به خوبی مدیریت کنید ​

۴. از شناسه‌های درخواست برای جستجوی هزینه استفاده کنید ​

۵. هدرها را برای رفع اشکال ثبت کنید ​

منابع مرتبط ​

هدرهای پاسخ

فهرست مطالب

هدرهای پیگیری درخواست

`avalai-request-id`

x-request-id (قدیمی، منسوخ)

خط زمانی مهاجرت

چرا هدر تغییر کرد

پنجره انتقالی

اقدام لازم

هدرهای متادیتای API

شناسه‌های درخواست سمت کلاینت

دسترسی به `avalai-request-id` از طریق SDKها

دسترسی به `avalai-request-id` با LangChain

هدرهای محدودیت نرخ

محدودیت‌های نرخ بر اساس درخواست

محدودیت‌های نرخ بر اساس توکن

هدرهای توکن در سطح پروژه

سطوح محدودیت نرخ

گردش‌کار retry مبتنی بر هدر

هدرهای HTTP استاندارد

Content-Type

Content-Length

Date

مثال‌ها

مثال کامل هدرهای پاسخ

بهترین شیوه‌ها

۱. همیشه `avalai-request-id` را ضبط کنید

۲. محدودیت‌های نرخ را به صورت فعال نظارت کنید

۳. پاسخ‌های ۴۲۹ را به خوبی مدیریت کنید

۴. از شناسه‌های درخواست برای جستجوی هزینه استفاده کنید

۵. هدرها را برای رفع اشکال ثبت کنید

منابع مرتبط