Responses API

Responses API رابط جدیدتر OpenAI است که ورودی/خروجی ساخت‌یافته، ابزارهای داخلی (جستجوی وب، جستجوی فایل، اجرای کد، تولید تصویر) و حالت‌های چندمرحله‌ای را یکجا دارد. نِت اَرز این endpoint را برای مدل‌های OpenAI به‌صورت عبور مستقیم (pass-through) ارائه می‌دهد؛ بدنه و پاسخ دقیقاً همان OpenAI است.

نمونهٔ ساده

response = client.responses.create(
    model="gpt-4.1-mini",
    instructions="کوتاه و رسمی پاسخ بدهید.",
    input="سه مزیت خرید از نِت اَرز را بنویسید.",
    max_output_tokens=300,
)
print(response.output_text)

ابزارهای داخلی

response = client.responses.create(
    model="gpt-4.1-mini",
    input="نرخ امروز دلار در بازار ایران را جست‌وجو کنید و در یک خط خلاصه بگویید.",
    tools=[{"type": "web_search"}],
)
print(response.output_text)
for item in response.output:
    if item.type == "web_search_call":
        print("جستجوی وب انجام شد →", item.status)

ابزارهای web_search، file_search، code_interpreter و image_generation پشتیبانی می‌شوند. برای هر فراخوانی ابزار، علاوه بر توکن‌ها، یک هزینهٔ ثابت به‌ازای هر فراخوانی به همان درخواست اضافه می‌شود که در گزارش درخواست و دفتر کل قابل مشاهده است.

ورودی چندرسانه‌ای

curl https://netarz.ir/api/ai/v1/responses \
  -H "Authorization: Bearer $NETARZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1-mini",
    "input": [
      {"role": "user", "content": [
        {"type": "input_text", "text": "این تصویر را توصیف کنید."},
        {"type": "input_image", "image_url": "https://example.com/photo.jpg"}
      ]}
    ]
  }'

استریم

با stream: true رویدادهای استاندارد Responses (response.output_text.delta، response.completed و…) به‌همان شکل عبور می‌کنند؛ usage در رویداد response.completed می‌آید.

with client.responses.stream(
    model="gpt-4.1-mini",
    input="یک داستان دوخطی بگویید.",
) as stream:
    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
    final = stream.get_final_response()
    print("\n", final.usage)

پارامترها و نکات

• input الزامی است (رشته یا آرایهٔ آیتم‌ها). instructions نقش system را دارد.
• max_output_tokens مبلغ رزرو اعتبار را کوچک می‌کند — مثل max_tokens در Chat Completions.
• previous_response_id و store: نِت اَرز فیلد store را حذف می‌کند و پاسخ‌ها در سمت OpenAI ذخیره نمی‌شوند؛ بنابراین گفت‌وگوهای چندمرحله‌ای را با فرستادن کامل تاریخچه در input ادامه دهید.
• reasoning: {"effort": "…"} برای مدل‌های o-series و GPT-5 پشتیبانی می‌شود؛ توکن‌های استدلال با قیمت خروجی محاسبه می‌شوند.
• شناسهٔ پاسخ (id) و هدر X-Request-Id شناسهٔ درخواست نِت اَرز است.