گفتگو و متن

تکمیل گفتگو

پاسخ یک مدل گفتگو را به قالب OpenAI می‌گیرید: متن ساده، استریم، فراخوانی ابزار و ورودی تصویر، با همان SDK رسمی OpenAI.

POST/v1/chat/completions

این مسیر اصلی گفتگو در API است و بدنه و پاسخ آن همان قالب OpenAI است. SDK رسمی OpenAI کافی است base_url را روی https://1ai.ir/v1 بگذارید و کلید 1ai را بدهید.

model نام کامل مدل است، مثل openai/gpt-6-luna. فهرست مدل‌هایی که کلید شما می‌تواند بزند را از فهرست مدل‌ها بگیرید و قیمت‌ها را در /models ببینید.

هزینه

پیش از اجرا، سقف هزینهٔ درخواست از اعتبار شما نگه داشته می‌شود و پس از پایان، فقط هزینهٔ واقعی کم می‌شود. اگر اعتبار برای سقف خروجی کافی نباشد ولی برای یک پاسخ کوتاه کافی باشد، سقف خروجی خودکار پایین می‌آید. اگر برای کمترین پاسخ هم کافی نباشد، خطای 402 insufficient_credits می‌گیرید. هزینهٔ درخواست غیر استریم در هدر x-1ai-credits برمی‌گردد. در استریم، با stream_options.include_usage در آخرین تکه به‌صورت usage.credits می‌آید.

استریم

با stream: true پاسخ به‌صورت رویدادهای data: می‌رسد و با data: [DONE] تمام می‌شود. تکهٔ مصرف فقط با stream_options.include_usage فرستاده می‌شود و choices آن خالی است. اگر بعد از شروع استریم خطایی رخ دهد، یک رویداد data: {"error": ...} و بعد [DONE] می‌آید. اگر اتصال را خودتان ببندید یا استریم وسط کار قطع شود، همان مقداری که تولید شده حساب می‌شود. جزئیات در استریم.

پارامترهای دیگر

فیلدهایی که در جدول نیامده، مثل seed یا presence_penalty، همان‌طور که هستند به مدل می‌رسند. اگر مدلی پارامتری را نپذیرد، خطای 400 provider_invalid_request می‌گیرید. فیلدهایی که مسیر یا سطح قیمت مدل را عوض می‌کنند (مثل models، provider، plugins، service_tier) بدون خطا کنار گذاشته می‌شوند.

پاسخ همیشه از فهرست فیلدهای مجاز ساخته می‌شود؛ فیلد دیگری از سمت مدل به شما نمی‌رسد. reasoning_content متن استدلال مدل است و reasoning_details را در نوبت بعدی ابزار همان‌طور که گرفتید پس بفرستید.

هدرهای پاسخ: x-request-id، x-1ai-cache-status و x-1ai-credits.

نمونه‌ها

curl https://1ai.ir/v1/chat/completions \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "openai/gpt-6-luna",
  "messages": [
    {
      "role": "system",
      "content": "You are a concise assistant."
    },
    {
      "role": "user",
      "content": "Explain what an API gateway does in two sentences."
    }
  ],
  "max_tokens": 200
}'
200پاسخ
{
  "id": "chatcmpl-0d3f6c52-8a1e-4c1b-9f57-2b7e1a64c9d0",
  "object": "chat.completion",
  "created": 1794484800,
  "model": "openai/gpt-6-luna",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "An API gateway is a single entry point that receives client requests and routes them to the right backend service. It also handles shared concerns such as authentication, rate limiting and logging."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 27,
    "completion_tokens": 40,
    "total_tokens": 67
  }
}

هدرها

  • Authorizationstringالزامی

    Bearer sk-1ai-... با کلید API شما. هدر x-api-key هم همین کار را می‌کند.

  • x-request-idstring

    شناسهٔ دلخواه شما برای پیگیری. نگه داشته می‌شود، ولی شناسهٔ پاسخ را خود 1ai می‌سازد و در هدر x-request-id برمی‌گرداند.

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

  • modelstringالزامی

    نام کامل مدل گفتگو، مثل openai/gpt-6-luna. حداکثر 120 نویسه.

  • messagesarrayالزامی

    گفتگو تا اینجا، از 1 تا 4096 پیام.

    ویژگی‌های داخلی
    • rolestringالزامی

      نقش فرستنده.

      مقادیر مجاز:systemdeveloperuserassistanttoolfunction
    • contentstring | array | null

      متن پیام، یا آرایه‌ای از بخش‌ها: { "type": "text", "text": "..." } و { "type": "image_url", "image_url": { "url": "..." } }. آدرس تصویر http(s) یا data URL است. پیام دستیار که فقط ابزار صدا زده می‌تواند null باشد.

    • tool_callsarray

      فراخوانی‌های ابزاری که دستیار در نوبت قبل خواسته. همان‌طور که در پاسخ آمده بود پس بفرستید. حداکثر 128 مورد.

    • tool_call_idstring

      در پیام tool: شناسهٔ فراخوانی‌ای که این نتیجه جوابش است. حداکثر 200 نویسه.

  • streambooleanپیش‌فرض: false

    پاسخ را به‌صورت رویدادهای SSE بفرست.

  • stream_optionsobject

    تنظیمات استریم.

    ویژگی‌های داخلی
    • include_usageboolean

      پیش از [DONE] یک تکهٔ آخر با usage (و هزینهٔ اعتباری در usage.credits) بفرست. choices آن تکه خالی است.

  • nintegerپیش‌فرض: 1

    تعداد پاسخ‌های جایگزین، از 1 تا 8.

  • max_tokensinteger

    سقف توکن خروجی، از 1 تا 10,000,000. اگر نگذارید، سقف خروجی خود مدل برای نگه‌داشتن اعتبار فرض می‌شود.

  • max_completion_tokensinteger

    مثل max_tokens؛ برای مدل‌های استدلالی که این نام را می‌خواهند. اگر هر دو بیایند، این یکی ملاک است.

  • temperaturenumber

    به مدل می‌رسد. مدلی که این پارامتر را نپذیرد خطا می‌دهد.

  • top_pnumber

    به مدل می‌رسد.

  • stopstring | array

    رشته‌هایی که تولید را متوقف می‌کنند. به مدل می‌رسد.

  • toolsarray

    ابزارهایی که مدل می‌تواند صدا بزند، حداکثر 128 مورد.

    ویژگی‌های داخلی
    • typestringالزامی

      برای ابزار تابعی function.

    • functionobjectالزامی

      شرح تابع.

      ویژگی‌های داخلی
      • namestringالزامی

        نام تابع.

      • descriptionstring

        توضیح اینکه تابع چه می‌کند و چه زمانی صدا زده شود.

      • parametersobject

        ورودی تابع به‌صورت JSON Schema.

      • strictboolean

        پیروی دقیق از طرح؛ به مدل می‌رسد و هر مدلی نمی‌پذیرد.

  • tool_choicestring | object

    none، auto، required یا { "type": "function", "function": { "name": "..." } }. به مدل می‌رسد.

  • parallel_tool_callsboolean

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

  • response_formatobject

    { "type": "json_object" } یا { "type": "json_schema", "json_schema": { "name": "...", "schema": { ... }, "strict": true } }. طرح json_schema در برآورد ورودی هم حساب می‌شود.

  • reasoning_effortstring

    میزان استدلال برای مدل‌های استدلالی، مثل low، medium یا high. به مدل می‌رسد.

خطاها

  • invalid_request400

    بدنه ناقص یا نادرست است؛ param فیلد مشکل‌دار را می‌گوید.

  • model_kind_mismatch400

    مدل از نوع گفتگو نیست، مثلاً مدل تصویر یا بردار را اینجا فرستاده‌اید.

  • context_length_exceeded400

    ورودی از پنجرهٔ متن مدل بلندتر است.

  • invalid_image_url400

    یکی از تصاویر خوانده نشد.

  • provider_invalid_request400

    مدل درخواست را نپذیرفت؛ پارامترها و پیام‌ها را بررسی کنید.

  • invalid_api_key401

    کلید نادرست، غیرفعال یا منقضی است.

  • insufficient_credits402

    اعتبار برای کمترین پاسخ هم کافی نیست. error.details شامل required و available است.

  • model_not_allowed403

    این کلید اجازهٔ استفاده از این مدل را ندارد.

  • model_not_found404

    مدل وجود ندارد یا در دسترس شما نیست.

  • rate_limit_exceeded429

    به سقف نرخ رسیده‌اید؛ هدر retry-after را ببینید. جزئیات در [محدودیت نرخ](/docs/rate-limits).

  • provider_service_unavailable503

    مدل موقتاً در دسترس نیست.

  • provider_timeout504

    مدل به‌موقع پاسخ نداد.

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