گفتگو و متن

پاسخ‌ها (قالب Responses)

قالب Responses شرکت OpenAI، بدون ذخیرهٔ گفتگو در سرور. Codex CLI و SDKهای تازهٔ OpenAI با آن به 1ai وصل می‌شوند.

POST/v1/responses

این مسیر قالب Responses شرکت OpenAI را برای هر مدل گفتگوی 1ai می‌پذیرد. Codex CLI با آن کار می‌کند.

بدون ذخیرهٔ گفتگو

1ai گفتگو را نگه نمی‌دارد: store همیشه false است و باید کل input را هر بار بفرستید. فیلدهای previous_response_id ، conversation ، background و prompt با 400 unsupported_parameter رد می‌شوند.

نام مدل

نام کامل مدل را بدهید، مثل openai/gpt-5.4-mini . نام‌هایی که با gpt- ، o و رقم، codex- یا chatgpt- شروع می‌شوند بدون صاحب هم پذیرفته می‌شوند: gpt-5.4-mini همان openai/gpt-5.4-mini است.

ابزارها

function و namespace روی همهٔ مدل‌ها کار می‌کنند. custom ، local_shell و tool_search سمت کلاینت فقط روی مدل‌های OpenAI که این قالب را مستقیم می‌فهمند کار می‌کنند، وگرنه 400 tool_unsupported . web_search فقط روی مدلی که قیمت جست‌وجوی وب دارد اجرا می‌شود و هر جست‌وجو جدا حساب می‌شود (پنج جست‌وجو از قبل نگه داشته می‌شود). روی مدل دیگر بدون خطا کنار گذاشته می‌شود، چون Codex آن را در هر نوبت می‌فرستد. هر ابزار دیگر (code_interpreter ، file_search ، mcp و مانند آن) 400 tool_unsupported می‌دهد.

استدلال

reasoning.effort و text.format (json_schema یا json_object) پذیرفته می‌شوند. آیتم reasoning با encrypted_content به همان مدل بسته است؛ در نوبت بعد همان‌طور که گرفتید پس بفرستید. استریم با رویدادهای response.* می‌رسد و رویداد آخر یکی از response.completed ، response.incomplete یا response.failed است. هزینهٔ درخواست غیر استریم در هدر x-1ai-credits می‌آید.

نمونه‌ها

curl https://1ai.ir/v1/responses \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "openai/gpt-5.4-mini",
  "instructions": "You are a concise assistant.",
  "input": "Give me a one-line summary of what HTTP caching does.",
  "max_output_tokens": 200
}'

200پاسخ

{
  "id": "resp_3e7a1c9d5b2f4a8e9c0d6b1f4a2e7c53",
  "object": "response",
  "created_at": 1794484800,
  "model": "openai/gpt-5.4-mini",
  "store": false,
  "tools": [],
  "tool_choice": "auto",
  "parallel_tool_calls": true,
  "metadata": {},
  "instructions": "You are a concise assistant.",
  "temperature": null,
  "top_p": null,
  "max_output_tokens": 200,
  "error": null,
  "incomplete_details": null,
  "status": "completed",
  "output": [
    {
      "id": "msg_3e7a1c9d5b2f4a8e9c0d6b1f0",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "HTTP caching stores copies of responses so repeat requests can be served without asking the origin server again.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 29,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 22,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 51
  }
}

هدرها

Authorizationstringالزامی
$Bearer sk-1ai-... با کلید API شما.$

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

modelstringالزامی
$نام کامل مدل، مثل openai/gpt-5.4-mini .$
inputstring | arrayالزامی
$یک رشته (یک پیام کاربر) یا آرایه‌ای از آیتم‌ها تا 8192 مورد: پیام با role (user ، assistant ، system ، developer) و content از بخش‌های input_text ، input_image و input_file ، و آیتم‌های function_call ، function_call_output و reasoning .$
instructionsstring
$دستور سیستمی.$
max_output_tokensinteger
$سقف توکن خروجی، از 1 تا 10,000,000.$
streambooleanپیش‌فرض: false
$پاسخ را به‌صورت رویدادهای response.* بفرست.$
toolsarray
$ابزارها، حداکثر 1024 مورد. ابزار تابعی به‌صورت تخت است، نه تو در تو.$
ویژگی‌های داخلی
- typestringالزامی
  $function ، namespace ، web_search ، custom ، local_shell یا tool_search .$
- namestring
  $نام تابع.$
- descriptionstring
  $توضیح کار تابع.$
- parametersobject
  $ورودی تابع به‌صورت JSON Schema.$
- strictboolean
  $پیروی دقیق از طرح.$
tool_choicestring | object
$none ، auto ، required یا { "type": "function", "name": "..." } .$
parallel_tool_callsboolean
$اجازهٔ چند فراخوانی ابزار در یک نوبت.$
temperaturenumber
$به مدل می‌رسد.$
top_pnumber
$به مدل می‌رسد.$
reasoningobject
$تنظیم استدلال.$
ویژگی‌های داخلی
- effortstring
  $میزان استدلال.$
  مقادیر مجاز:minimallowmediumhighxhighmax
textobject
$قالب متن خروجی.$
ویژگی‌های داخلی
- formatobject
  ${ "type": "json_schema", "name": "...", "schema": { ... }, "strict": true } یا { "type": "json_object" }.$
storeboolean
$نادیده گرفته می‌شود؛ همیشه false .$

خطاها

unsupported_parameter400
previous_response_id، conversation، background یا prompt فرستاده‌اید.
tool_unsupported400
نوع ابزار روی این مدل در دسترس نیست.
invalid_request400
بدنه نادرست است؛ param فیلد مشکل‌دار را می‌گوید.
invalid_api_key401
کلید نادرست، غیرفعال یا منقضی است.
insufficient_credits402
اعتبار کافی نیست.
model_not_found404
مدل وجود ندارد یا در دسترس شما نیست.
rate_limit_exceeded429
به سقف نرخ رسیده‌اید.

پاسخ‌ها (قالب Responses)

بدون ذخیرهٔ گفتگو

نام مدل

ابزارها

استدلال

نمونه‌ها

هدرها

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

خطاها

صفحه‌های مرتبط