تغییر هدر شناسه درخواست: جایگزینی x-request-id با avalai-request-id

Date: ۱۴۰۵-۰۵-۲۵ / (2026-08-16)

خلاصه

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

---

جزئیات

چرا این تغییر

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

برای اینکه شناسه درخواست قطعی بماند، AvalAI از این پس آن را در هدر اختصاصی avalai-request-id برمی‌گرداند. خود شناسه تغییری نمی‌کند: همچنان UUID v7 است، همچنان از endpoint /user/v1/transactions/lookup پشتیبانی می‌کند و با فیلدهای request_id برگردانده‌شده در بدنه پاسخ‌ها مانند Videos API یکسان است.

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

فاز	تاریخ	رفتار
آغاز پنجره	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-request-id ممکن است از CDN آمده باشد

در طول پنجره ۶۰ روزه، خواندن هر کدام از دو هدر به همان درخواست اشاره می‌کند. کد خود را پیش از پایان پنجره به خواندن avalai-request-id به‌روزرسانی کنید.

نمونه هدرهای پاسخ

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

مثال درخواست

curl -i https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": "یک health check یک‌خطی برگردان."
      }
    ]
  }'

پرچم -i هدرهای پاسخ را چاپ می‌کند تا بتوانید در طول پنجره انتقالی هر دو هدر شناسه درخواست را مشاهده کنید.

مثال‌های مهاجرت

avalai-request-id را از هدرهای پاسخ بخوانید. در طول پنجره می‌توانید بازگشت (fallback) به x-request-id را موقتا نگه دارید؛ آن را پیش از 2026-10-15 (۱۴۰۵-۰۷-۲۳) حذف کنید.

Bash

# مشاهده هدر جدید در هر پاسخ
curl -sI -X POST https://api.avalai.ir/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{"model": "gpt-5.4-mini", "messages": [{"role": "user", "content": "سلام"}]}' \
  | grep -i "avalai-request-id"

# 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": "سلام"}]},
)

# هدر جدید (پس از 2026-10-15 (۱۴۰۵-۰۷-۲۳) الزامی است)
request_id = response.headers.get("avalai-request-id")

# بازگشت موقت پنجره انتقالی؛ پیش از 2026-10-15 (۱۴۰۵-۰۷-۲۳) حذف شود
request_id = response.headers.get("avalai-request-id") or response.headers.get(
    "x-request-id"
)

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

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: "سلام" }],
  }),
});

// هدر جدید (پس از 2026-10-15 (۱۴۰۵-۰۷-۲۳) الزامی است)
const requestId = response.headers.get("avalai-request-id");

// بازگشت موقت پنجره انتقالی؛ پیش از 2026-10-15 (۱۴۰۵-۰۷-۲۳) حذف شود
const fallbackId =
  response.headers.get("avalai-request-id") ?? response.headers.get("x-request-id");

console.log(`شناسه درخواست: ${requestId}`);

OpenAI SDK

SDKهای OpenAI هدرهای خام پاسخ را از طریق raw-response API در اختیار می‌گذارند:

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")

برای الگوهای کامل SDK و LangChain به مرجع هدرهای پاسخ مراجعه کنید.

معنای این تغییر برای کاربران AvalAI

• شناسه‌های درخواست همچنان UUID v7 هستند و رفتار آن‌ها برای lookup هزینه و پشتیبانی تغییری نمی‌کند
• هر دو هدر تا 2026-10-15 (۱۴۰۵-۰۷-۲۳) برگردانده می‌شوند، بنابراین قطعی فوری رخ نمی‌دهد
• پس از 2026-10-15 (۱۴۰۵-۰۷-۲۳)، فقط هدر avalai-request-id را بخوانید و دیگر به x-request-id اعتماد نکنید
• پیگیری هزینه نمایندگان از طریق /user/v1/transactions/lookup با همان شناسه‌ها به کار خود ادامه می‌دهد
• هدر درخواست X-Client-Request-Id و فیلدهای request_id در بدنه پاسخ تحت تأثیر این تغییر نیستند

---

پیوندهای مرتبط

• هدرهای پاسخ - مرجع کامل هدرها و خط زمانی مهاجرت
• مرجع User API - جستجوی تراکنش با شناسه درخواست
• راهنمای پیگیری هزینه نمایندگان - پیگیری دقیق هزینه هر درخواست
• مدیریت خطا - ارتباط timeoutها و خطاها با شناسه‌های درخواست