Responses API

Responses API قرارداد جدیدتر OpenAI برای ساخت پاسخ است. اگر Chat Completions را مسیر کلاسیک چت بدانیم، Responses API تلاش می‌کند ورودی، دستور کلی، ابزارها، خروجی و جریان‌های استدلالی را در یک مدل یکپارچه‌تر کنار هم قرار دهد.

عملیات پشتیبانی‌شده

گدارAI همه عملیات منبع Responses در OpenAI را از مسیرهای عمومی /v1 در دسترس قرار می‌دهد:

روش	مسیر	کاربرد
POST	/v1/responses	ساخت پاسخ
POST	/v1/responses/compact	فشرده‌سازی زمینه یک گفت‌وگوی طولانی
POST	/v1/responses/input_tokens	شمارش توکن‌های ورودی پیش از ساخت پاسخ
GET	/v1/responses/{response_id}	بازیابی پاسخ
DELETE	/v1/responses/{response_id}	حذف پاسخ ذخیره‌شده
POST	/v1/responses/{response_id}/cancel	لغو پاسخ پس‌زمینه
GET	/v1/responses/{response_id}/input_items	دریافت فهرست ورودی‌های پاسخ

گدارAI شناسه پاسخ را به همان حساب OpenAI که پاسخ را ساخته متصل می‌کند. در نتیجه، عملیات بازیابی، لغو، حذف و دریافت ورودی‌ها به حساب ارائه‌دهنده دیگری مسیریابی نمی‌شوند.

:::warning محدودیت فعلی

حالت پایدار WebSocket در OpenAI هنوز از مسیر عمومی گدارAI در دسترس نیست. در حال حاضر از درخواست عادی HTTP و جریان SSE استفاده کنید.

:::

مدل‌های OpenAI بررسی‌شده

پشتیبانی Responses برای این مدل‌ها در کاتالوگ گدارAI ثبت شده است:

• gpt-5.6-sol، gpt-5.6-terra و gpt-5.6-luna
• gpt-5.5 و gpt-5.5-pro
• gpt-5.4، gpt-5.4-pro، gpt-5.4-mini و gpt-5.4-nano

همه این مدل‌ها ورودی متنی و تصویری و خروجی متنی دارند. ورودی یا خروجی صوتی و ویدئویی برای آن‌ها پشتیبانی نمی‌شود. جریان SSE برای همه مدل‌های این فهرست به‌جز gpt-5.5-pro قابل استفاده است. ابزارهای مجاز هر مدل در کاتالوگ ثبت شده‌اند و ممکن است با مدل دیگر متفاوت باشند.

چه زمانی از Responses API استفاده کنیم؟

این API را انتخاب کنید وقتی:

• اپلیکیشن شما از ابتدا بر اساس قرارداد OpenAI Responses طراحی شده است.
• می‌خواهید از input و instructions به‌جای آرایه کلاسیک messages استفاده کنید.
• با SDKها یا ابزارهایی کار می‌کنید که client.responses.create را مبنا قرار داده‌اند.
• می‌خواهید مسیر تولید پاسخ شما به قراردادهای جدیدتر OpenAI نزدیک بماند.

اگر تیم شما قبلاً روی Chat Completions و آرایه messages کار کرده، ادامه دادن همان مسیر معمولاً ساده‌تر است.

شروع سریع

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

Python

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/responses",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai:default:gpt-4o-mini",
        "instructions": "You are a concise Persian technical assistant.",
        "input": "برای من سه مزیت استفاده از درگاه مدل‌های زبانی را بنویس.",
    },
    timeout=60,
)

response.raise_for_status()
print(response.json()["output_text"])

NodeJS

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai:default:gpt-4o-mini",
    instructions: "You are a concise Persian technical assistant.",
    input: "برای من سه مزیت استفاده از درگاه مدل‌های زبانی را بنویس.",
  }),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data.output_text);

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/responses" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai:default:gpt-4o-mini",
    "instructions": "You are a concise Persian technical assistant.",
    "input": "برای من سه مزیت استفاده از درگاه مدل‌های زبانی را بنویس."
  }'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

response = client.responses.create(
    model="openai:default:gpt-4o-mini",
    instructions="You are a concise Persian technical assistant.",
    input="برای من سه مزیت استفاده از درگاه مدل‌های زبانی را بنویس.",
)

print(response.output_text)

OpenAI NodeJS SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const response = await client.responses.create({
  model: "openai:default:gpt-4o-mini",
  instructions: "You are a concise Persian technical assistant.",
  input: "برای من سه مزیت استفاده از درگاه مدل‌های زبانی را بنویس.",
});

console.log(response.output_text);

مدل انتخابی باید در فضای کاری شما مجاز و با Responses API سازگار باشد. اگر این مسیر برای ارائه‌دهنده یا مدل خاصی در محیط شما فعال نباشد، درخواست با خطای دسترسی یا ناسازگاری برمی‌گردد.

درخواست ساده و ادامه پاسخ

برای ساخت یک پاسخ تازه، معمولاً model و input را می‌فرستید:

{
  "model": "openai:default:gpt-4o-mini",
  "input": "تفاوت سقف نرخ و سقف بودجه را توضیح بده."
}

instructions برای تعیین رفتار کلی مدل استفاده می‌شود؛ چیزی شبیه پیام سیستمی در Chat Completions. input داده اصلی کاربر یا کاری است که مدل باید روی آن پاسخ بسازد.

در ادامه یک پاسخ قبلی، قرارداد OpenAI اجازه می‌دهد model حذف شود. گدارAI مدل و حساب OpenAI را از نگاشت امن previous_response_id پیدا می‌کند و همان درخواست را بدون افزودن فیلد model به OpenAI می‌فرستد:

{
  "previous_response_id": "resp_123",
  "input": "حالا همین پاسخ را کوتاه‌تر کن."
}

پارامترهای مهم

پارامتر	کاربرد
temperature	میزان تنوع پاسخ؛ معمولاً بین 0 و 2.
top_p	کنترل نمونه‌برداری؛ معمولاً بین 0 و 1.
max_output_tokens	سقف توکن خروجی.
stream	فعال‌کردن پاسخ جریانی.
tools و tool_choice	تعریف ابزارها، اگر مدل و ارائه‌دهنده پشتیبانی کنند.
user	شناسه کاربر نهایی برای ردیابی و کنترل‌های سمت اپلیکیشن.
service_tier	انتخاب پردازش standard، flex یا fast در مدل‌های سازگار. مقدار قدیمی priority نیز برای Fast پذیرفته می‌شود.

نکته آموزشی: max_output_tokens را با max_tokens در Chat Completions اشتباه نگیرید. هر دو سقف خروجی را کنترل می‌کنند، اما نام پارامترها در قراردادها متفاوت است.

حافظه نهان پاسخ

برای جلوگیری از فراخوانی دوباره ارائه‌دهنده در درخواست‌های تکراری، سرآیند x-godarai-cache-config را همراه POST /v1/responses بفرستید. حالت simple کل بدنه درخواست را با تطبیق دقیق بررسی می‌کند؛ حالت smart متن آخرین ورودی کاربر را به‌صورت معنایی مقایسه می‌کند و بقیه پارامترها باید یکسان بمانند.

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/responses" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --header 'x-godarai-cache-config: {"type":"simple","ttl":600,"namespace":"support"}' \
  --data '{
    "model": "openai:default:gpt-4o-mini",
    "instructions": "پاسخ را کوتاه و دقیق بنویس.",
    "input": "چطور رمز عبورم را بازیابی کنم؟"
  }'

همین درخواست را دوباره بفرستید. در درخواست نخست، سرآیند پاسخ x-godarai-cache-status: miss است؛ پس از ذخیره پاسخ، درخواست یکسان با x-godarai-cache-status: hit برمی‌گردد. در پاسخ برگرفته از حافظه نهان، x-godarai-cached-trace-id نیز شناسه رد درخواست اصلی را نشان می‌دهد.

برای تطبیق معنایی، مقدار type را به smart تغییر دهید و در صورت نیاز similarity_threshold را تنظیم کنید. درخواست‌های جریانی، درخواست‌های دارای background: true و درخواست‌هایی که conversation یا previous_response_id دارند، در هر دو حالت با وضعیت bypass به مسیر عادی ارائه‌دهنده می‌روند. در حالت smart، درخواست‌های دارای tools یا tool_choice و ورودی‌های تصویری، فایلی یا غیرمتنی نیز از حافظه نهان عبور می‌کنند.

جزئیات ttl، namespace، آستانه شباهت و عیب‌یابی را در راهنمای حافظه نهان پاسخ بخوانید.

پاسخ جریانی

Python

import requests

with requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/responses",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "model": "openai:default:gpt-4o-mini",
        "input": "یک معرفی کوتاه از گدارAI بنویس.",
        "stream": True,
    },
    stream=True,
    timeout=60,
) as response:
    response.raise_for_status()
    for line in response.iter_lines(decode_unicode=True):
        if line:
            print(line)

NodeJS

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai:default:gpt-4o-mini",
    input: "یک معرفی کوتاه از گدارAI بنویس.",
    stream: true,
  }),
});

if (!response.ok || !response.body) {
  throw new Error(`Request failed with status ${response.status}`);
}

const decoder = new TextDecoder();
for await (const chunk of response.body) {
  process.stdout.write(decoder.decode(chunk));
}

REST API

curl --no-buffer --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/responses" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai:default:gpt-4o-mini",
    "input": "یک معرفی کوتاه از گدارAI بنویس.",
    "stream": true
  }'

OpenAI Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_GODARAI_TOKEN",
    base_url="https://YOUR_WORKSPACE.godarai.ir/v1",
)

stream = client.responses.create(
    model="openai:default:gpt-4o-mini",
    input="یک معرفی کوتاه از گدارAI بنویس.",
    stream=True,
)

for event in stream:
    print(event)

OpenAI NodeJS SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "YOUR_GODARAI_TOKEN",
  baseURL: "https://YOUR_WORKSPACE.godarai.ir/v1",
});

const stream = await client.responses.create({
  model: "openai:default:gpt-4o-mini",
  input: "یک معرفی کوتاه از گدارAI بنویس.",
  stream: true,
});

for await (const event of stream) {
  console.log(event);
}

در حالت جریانی، رابط کاربری زودتر شروع به نمایش پاسخ می‌کند، اما سرویس شما باید رویدادها را درست جمع‌آوری کند و وضعیت پایان، خطا و مصرف نهایی را جداگانه مدیریت کند.

تفاوت با Chat Completions

موضوع	Chat Completions	Responses API
ورودی اصلی	messages	input و instructions
نقطه شروع برای بیشتر نمونه‌ها	بسیار رایج	جدیدتر و در حال رشد
مهاجرت از ابزارهای قدیمی‌تر	معمولاً ساده‌تر	نیازمند بازبینی قرارداد درخواست و پاسخ
انتخاب پیشنهادی	اتصال‌های چت و عامل‌محور رایج	پروژه‌های جدیدتر مبتنی بر Responses

هیچ‌کدام به‌تنهایی «بهتر» نیستند؛ انتخاب درست به قرارداد اپلیکیشن شما، مدل‌های مجاز و قابلیت فعال در محیطتان بستگی دارد.

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

برای مدیریت پاسخ، مقدار id برگشتی از POST /v1/responses را نگه دارید. سپس همان شناسه را در مسیرهای بازیابی، حذف، لغو یا دریافت ورودی‌ها قرار دهید.

برای ادامه پاسخ جریانی ذخیره‌شده، پارامترهای stream=true و starting_after را به درخواست بازیابی اضافه کنید:

curl --no-buffer \
  "https://YOUR_WORKSPACE.godarai.ir/v1/responses/resp_123?stream=true&starting_after=10" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN"

برای صفحه‌بندی ورودی‌های پاسخ، از after، limit و order استفاده کنید. مقدار limit باید بین 1 و 100 باشد.

هشدار

عملیات لغو فقط برای پاسخی معتبر است که با "background": true ساخته شده باشد. پاسخ حذف‌شده دیگر از OpenAI قابل‌بازیابی نیست.

خطاهای رایج

• Model access denied or unsupported for responses: مدل برای این API مجاز یا سازگار نیست.
• Response provider account is ambiguous: درخواست بدون مدل یا شناسه پاسخ قبلی ارسال شده و بیش از یک حساب OpenAI می‌تواند مقصد باشد.
• خطاهای اعتبارسنجی OpenAI با همان type، code، param و فیلدهای تکمیلی ارائه‌دهنده برگردانده می‌شوند؛ بنابراین برای تشخیص علت، فقط متن message را بررسی نکنید.

هدرهای X-Request-Id، Retry-After و هدرهای X-Ratelimit-{Limit,Remaining,Reset}-{Requests,Tokens} نیز از OpenAI به برنامه شما منتقل می‌شوند.

جمع‌بندی

Responses API برای تیم‌هایی مناسب است که می‌خواهند با قرارداد جدیدتر OpenAI کار کنند و مسیر پاسخ‌سازی خود را بر اساس input، instructions و رویدادهای جدیدتر طراحی کنند. برای شروع مطمئن، آن را با یک مدل مجاز، درخواست کوچک و بررسی دقیق گزارش رخدادها آزمایش کنید.