Create a response
یک پاسخ جریانی یا غیرجریانی با فرمت OpenResponses ایجاد میکند.
نقطهٔ پایانی POST /responses با فرمت
OpenResponses (سازگار با OpenAI Responses API) یک پاسخ ایجاد میکند و از هر دو حالت
stream: false (پاسخ کامل) و stream: true
(رویدادهای جریانی) پشتیبانی میکند.
Endpoint
POST
/responses
https://app.asha-ai.ir/v1/responsesهدرها
| هدر | نوع | توضیح |
|---|---|---|
Authorization |
string | احراز هویت؛ Bearer <ASHA_API_KEY>. |
X-OpenRouter-Metadata |
string |
نمایان کردن فرادادهٔ مسیریابی در پاسخ تحت openrouter_metadata؛
مقدار disabled (پیشفرض) یا enabled.
هدر قدیمی X-OpenRouter-Experimental-Metadata نیز برای سازگاری
پذیرفته میشود.
|
پارامترهای درخواست
| پارامتر | نوع | توضیح |
|---|---|---|
model |
string | مدل مورد استفاده برای پاسخ (مثل openai/gpt-4o). |
input |
string | array |
ورودی درخواست؛ یک رشتهٔ ساده یا آرایهای از آیتمها
(مثل پیامهایی با type: message و
role و content).
|
instructions |
string | null | دستورالعمل سیستم (غیراجباری). |
stream |
boolean | در صورت true پاسخ بهصورت جریانی رویدادها برمیگردد. پیشفرض false. |
max_output_tokens |
integer | null | حداکثر تعداد توکن خروجی. |
temperature |
number | null | پارامتر نمونهبرداری دما. |
top_p |
number | null | پارامتر top-p. |
top_k |
integer | پارامتر top-k. |
presence_penalty |
number | null | جریمهٔ حضور. |
frequency_penalty |
number | null | جریمهٔ تکرار. |
tools |
array |
ابزارها؛ شامل توابع (type: function) و سرویسابزارهای سمت سرور
(مثل openrouter:web_search، جستجوی وب،
file_search، code_interpreter و …).
|
tool_choice |
auto | none | required | object | انتخاب ابزار؛ مقدار پیشفرض auto. |
parallel_tool_calls |
boolean | null | اجازه به فراخوانی موازی ابزارها. |
metadata |
object | null | فرادادهٔ درخواست؛ حداکثر ۱۶ جفت کلید/مقدار، کلیدها ≤۶۴ کاراکتر بدون براکت و مقدارها ≤۵۱۲ کاراکتر. |
modalities |
array | حالتهای خروجی؛ مقادیر پشتیبانیشده text و image. |
include |
array | null | محتوای اضافه برای پاسخ (مثل message.input_image.image_url). |
reasoning |
object | null | پیکربندی استدلال؛ enabled، effort، max_tokens و summary. |
text |
object | پیکربندی خروجی متن شامل format (مثل text، json_object) و verbosity. |
truncation |
auto | disabled | null | مدیریت برش متن. |
provider |
object | null |
ترجیحات مسیریابی: order، allow_fallbacks،
only، ignore، max_price،
sort و …
|
service_tier |
string | null | سطح سرویس: auto (پیشفرض)، default، fast (معادل priority)، flex، priority، scale. |
session_id |
string |
شناسهٔ یکتا برای گروهبندی درخواستهای مرتبط (حداکثر ۲۵۶ کاراکتر)؛ بهعنوان کلید
مسیریابی چسبنده برای بیشترین ضربهٔ کش پرامپت استفاده میشود. مقدار بدنه بر هدر
x-session-id مقدم است.
|
user |
string | شناسهٔ یکتای کاربر نهایی (حداکثر ۲۵۶ کاراکتر) برای تفکیک abuse. |
safety_identifier |
string | null | شناسهٔ هششدهٔ پیشنهادی برای جداسازی abuse هر کاربر. |
models |
array | فهرست الگوهای مدل برای مسیریابی خودکار. |
plugins |
array |
پلاگینهای فعال این درخواست: auto-router،
auto-beta-router، context-compression،
file-parser، fusion،
moderation، pareto-router،
response-healing، web،
web-fetch.
|
max_tool_calls |
integer | null | حداکثر مراحل agent برای ابزارهای سمت سرور؛ پیشفرض و سقف ۳۰. |
stop_server_tools_when |
array | شرایط توقف حلقهٔ ابزار سمت سرور؛ هر شرط فعال شونده حلقه را متوقف میکند (OR). |
store |
boolean | بهصورت مستقیم به ارائهدهنده فرستاده میشود؛ پشتیبانی از نگهداری وضعیت به ارائهدهندهٔ بالادستی بستگی دارد. |
previous_response_id |
string | null |
بهصورت مستقیم به ارائهدهنده فرستاده میشود. برای گفتگوهای چندنوبته، تاریخچهٔ کامل را در
input بفرستید.
|
debug |
object | گزینههای دیباگ برای بازرسی تغییرات درخواست (فقط حالت جریانی). |
trace |
object | فرادادهٔ ردیابی/مشاهدهپذیری: trace_id، span_name و … |
prompt |
object | null | قالب پرامپت ذخیرهشده با id و variables. |
cache_control |
object | فعالسازی کش خودکار پرامپت؛ نوع ephemeral و اختیاری ttl. |
top_logprobs |
integer | null | تعداد احتمالات لگاریتمی برتر برای هر توکن. |
background |
boolean | null | اجرای پاسخ در پسزمینه. |
احراز هویت
با کلید API آشا از طریق هدر
Authorization: Bearer <ASHA_API_KEY>
احراز هویت کنید.
مثال درخواست
curl https://app.asha-ai.ir/v1/responses
-H "Authorization: Bearer $ASHA_API_KEY"
-H "Content-Type: application/json"
-d '{
"model": "openai/gpt-4o",
"input": "Tell me a joke"
}'import requests
response = requests.post(
'https://app.asha-ai.ir/v1/responses',
headers={
'Authorization': 'Bearer <ASHA_API_KEY>',
'Content-Type': 'application/json',
},
json={
'model': 'openai/gpt-4o',
'input': 'Tell me a joke',
},
)
data = response.json()
print(data['output'][0]['content'][0]['text'])
print(data['usage']['total_tokens'])const response = await fetch(
'https://app.asha-ai.ir/v1/responses',
{
method: 'POST',
headers: {
'Authorization': 'Bearer <ASHA_API_KEY>',
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: 'openai/gpt-4o',
input: 'Tell me a joke',
}),
}
);
const data = await response.json();
console.log(data.output[0].content[0].text);پاسخ موفق
در صورت موفقیت، پاسخ با کد 200 برمیگردد:
JSON
200 OK
{
"id": "resp_abc123",
"object": "response",
"created_at": 1700000000,
"completed_at": 1700000010,
"model": "openai/gpt-4o",
"status": "completed",
"output": [
{
"id": "msg_abc123",
"type": "message",
"role": "assistant",
"status": "completed",
"content": [
{
"type": "output_text",
"text": "Why did the chicken cross the road? To get to the other side!",
"annotations": []
}
]
}
],
"usage": {
"input_tokens": 10,
"input_tokens_details": { "cached_tokens": 0 },
"output_tokens": 20,
"output_tokens_details": { "reasoning_tokens": 0 },
"total_tokens": 30
},
"error": null,
"incomplete_details": null,
"tools": [],
"tool_choice": "auto",
"parallel_tool_calls": true,
"instructions": null,
"metadata": null
}پاسخ جریانی
با تنظیم stream: true پاسخ بهصورت رویدادهای
text/event-stream (SSE) ارسال میشود که با تعدادی
data: و در پایان
data: [DONE] خاتمه مییابد:
SSE
text/event-stream
data: {"type":"response.created","sequence_number":0,"response":{...}}
data: {"type":"response.in_progress","sequence_number":1,"response":{...}}
data: {"type":"response.output_item.added","sequence_number":2,"item":{...}}
data: {"type":"response.content_part.added","sequence_number":3,"part":{...}}
data: {"type":"response.output_text.delta","sequence_number":4,"delta":"Hello","item_id":"item-1","content_index":0,"output_index":0,"logprobs":[]}
data: {"type":"response.output_text.done","sequence_number":6,"text":"Hello! How can I help you?"}
data: {"type":"response.output_item.done","sequence_number":8,"item":{...}}
data: {"type":"response.completed","sequence_number":10,"response":{...}}
data: [DONE]رویدادهای جریانی
| رویداد | توضیح |
|---|---|
response.created | پاسخ ایجاد شد. |
response.in_progress | پاسخ در حال پردازش است. |
response.completed | پاسخ با موفقیت کامل شد. |
response.incomplete | پاسخ ناقص بود. |
response.failed | پاسخ شکست خورد. |
response.output_item.added | آیتم خروجی جدیدی به پاسخ اضافه شد. |
response.output_item.done | یک آیتم خروجی کامل شد. |
response.content_part.added | بخش محتوای جدیدی اضافه شد. |
response.content_part.done | یک بخش محتوا کامل شد. |
response.output_text.delta | تکهٔ متنی جدید در جریان ارسال میشود. |
response.output_text.done | متن کامل شد. |
response.output_text.annotation.added | حاشیهنویسی (مثل citation) اضافه شد. |
response.reasoning_text.delta / .done | استدلال در جریان و پایان آن. |
response.reasoning_summary_part.added / .done | بخش خلاصهٔ استدلال. |
response.reasoning_summary_text.delta / .done | متن خلاصهٔ استدلال. |
response.refusal.delta / .done | امتناع از پاسخ. |
response.function_call_arguments.delta / .done | آرگومانهای فراخوانی تابع. |
response.custom_tool_call_input.delta / .done | ورودی ابزار سفارشی. |
response.code_interpreter_call.* | رویدادهای مفسر کد (in_progress، interpreting، completed و …). |
response.web_search_call.* | رویدادهای جستجوی وب (in_progress، searching، completed). |
response.image_generation_call.* | رویدادهای تولید تصویر (in_progress، generating، partial_image، completed). |
response.apply_patch_call_operation_diff.delta / .done | تفاوتهای عملیات patch. |
response.fusion_call.* | رویدادهای پلاگین fusion (panel، analysis و …). |
response.debug | رویداد دیباگ هنگام فعال بودن debug.echo_upstream_body. |
error | خطای رخداده در حین جریان؛ شامل code، message و param. |
خطاها
| کد | توضیح |
|---|---|
400 | پارامترهای درخواست نامعتبر است یا ورودی بدشکل است. |
401 | هدر احراز هویت وجود ندارد یا اعتبارنامه نامعتبر است. |
402 | اعتبار کافی نیست؛ برای تکمیل درخواست باید موجودی افزوده شود. |
429 | محدودیت نرخ رد شد. |
500 | خطای داخلی سرور. |
502 | پروایدر/بالادست خطا برگرداند. |