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

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

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

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

هدرهای پاسخ

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

فهرست مطالب

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

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

x-request-id

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

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

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

فرمت: UUID v7 (مثلا 019ac4a0-a8f4-7041-845f-3ea8f15dcf1a)

مثال:

x-request-id: 019ac4a0-a8f4-7041-845f-3ea8f15dcf1a

هدرهای متادیتای 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 همچنان x-request-id به‌همراه transaction lookup در User API است.

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

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

این هدر وقتی مفید است که timeout یا خطای شبکه اجازه ندهد برنامه شما هدرهای پاسخ را دریافت کند. اگر route انتخابی AvalAI metadata سازگار با OpenAI را حفظ کند، پشتیبانی می‌تواند از client request ID شما به‌عنوان کلید دوم برای پیگیری استفاده کند. مقدار را فقط ASCII، حداکثر ۵۱۲ کاراکتر و یکتا برای هر درخواست نگه دارید. این هدر جایگزین x-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 یک‌خطی برگردان."
  }'

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

هنگام استفاده از SDK های رسمی مانند OpenAI Python SDK، هدر x-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",
)

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

# دسترسی مستقیم به شناسه درخواست از شیء پاسخ
request_id = response._request_id
print(f"شناسه درخواست: {request_id}")
# خروجی: شناسه درخواست: 019ac4a0-a8f4-7041-845f-3ea8f15dcf1a

نسخه معادل 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 بررسی کنید.

توجه

ویژگی _request_id در تمام اشیاء پاسخ برگردانده شده توسط OpenAI SDK هنگام پیکربندی با آدرس پایه AvalAI در دسترس است. این روش توصیه شده است زیرا تجزیه هدر را به طور خودکار انجام می‌دهد.

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

LangChain به طور مستقیم هدرهای پاسخ HTTP خام را از فراخوانی‌های API زیرساختی نمایش نمی‌دهد. با این حال، می‌توانید هدر x-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("x-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("x-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 امنیت نخ را هنگام ارسال درخواست‌های همزمان تضمین می‌کند.

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

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

SDK/روش	نحوه دسترسی
پایتون (OpenAI)	`response._request_id`
پایتون (requests)	`response.headers.get("x-request-id")`
جاوااسکریپت (fetch)	`response.headers.get("x-request-id")`
Go (net/http)	`resp.Header.Get("x-request-id")`
PHP (curl)	استخراج از هدرهای پاسخ

برای نمایندگان فروش: این هدر برای کسب‌وکار شما حیاتی است. همیشه آن را ضبط و ذخیره کنید تا هزینه دقیق هر فراخوانی 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 درخواست‌های بیش از حد

اگر از محدودیت‌های نرخ خود فراتر روید، یک کد وضعیت 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ها، به‌جای تلاش کورکورانه از هدرهای پاسخ استفاده کنید:

ابتدا x-request-id را ذخیره کنید. قبل از parse کردن body آن را log کنید تا پشتیبانی، lookup هزینه نمایندگان و trace داخلی به همان درخواست اشاره کنند.
در خطای 429 به 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ها تمام شدند، پیام روشن «بعدا دوباره تلاش کنید» به کاربر بدهید و x-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: 019ac4a0-a8f4-7041-845f-3ea8f15dcf1a

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("x-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("x-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("x-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('/x-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 بررسی کنید.

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

1. همیشه x-request-id را ضبط کنید

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

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

اگر X-Client-Request-Id هم می‌فرستید، هر دو شناسه را کنار هم log کنید تا گزارش timeoutها و پاسخ‌های موفق قابل correlate باشند.

python

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

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

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

python

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

3. پاسخ‌های 429 را به خوبی مدیریت کنید

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

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("حداکثر تلاش‌های مجدد فراتر رفت")

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

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

python

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

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

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

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

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

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

python

import logging

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

منابع مرتبط

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

هدرهای پاسخ ​

فهرست مطالب ​

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

x-request-id ​

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

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

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

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

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

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

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

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

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

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

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

Content-Type ​

Content-Length ​

Date ​

مثال‌ها ​

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

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

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

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

3. پاسخ‌های 429 را به خوبی مدیریت کنید ​

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

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

منابع مرتبط ​

هدرهای پاسخ

فهرست مطالب

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

x-request-id

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

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

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

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

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

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

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

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

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

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

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

Content-Type

Content-Length

Date

مثال‌ها

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

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

1. همیشه x-request-id را ضبط کنید

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

3. پاسخ‌های 429 را به خوبی مدیریت کنید

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

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

منابع مرتبط