گفتگو و متن

پیام‌ها (قالب Anthropic)

قالب Messages شرکت Anthropic برای همهٔ مدل‌های گفتگو. SDK رسمی Anthropic و Claude Code با همین مسیر به 1ai وصل می‌شوند.

POST/v1/messages

این مسیر همان POST /v1/messages شرکت Anthropic است، ولی هر مدل گفتگوی 1ai را می‌پذیرد، نه فقط Claude. Claude Code با همین مسیر روی کلید 1ai کار می‌کند: ANTHROPIC_BASE_URL را https://1ai.ir بگذارید و کلید را در ANTHROPIC_AUTH_TOKEN بدهید.

احراز هویت

کلید را در هدر x-api-key بفرستید (SDK Anthropic همین کار را می‌کند) یا مثل بقیهٔ API در Authorization: Bearer. هدرهای anthropic-version و anthropic-beta پذیرفته می‌شوند. آدرس پایه برای SDK، https://1ai.ir است، نه https://1ai.ir/v1، چون SDK خودش /v1/messages را اضافه می‌کند.

نام مدل

نام کامل مدل را بدهید، مثل anthropic/claude-sonnet-5.5. نام‌های Anthropic هم شناخته می‌شوند: claude-sonnet-5-5، با تاریخ یا [1m] در انتها، به همان مدل می‌رسد. مدل‌های غیر Claude را هم با نام کامل می‌توانید بزنید.

پاسخ و خطا

پاسخ همان قالب Anthropic است: type: "message"، آرایهٔ content از بلوک‌ها و stop_reason. در استریم، رویدادها نام دارند (message_start تا message_stop). خطاها هم قالب Anthropic دارند، حتی خطای کلید و JSON نادرست: { "type": "error", "error": { "type": "...", "message": "..." }, "request_id": "..." }.

فکر کردن، کش و ابزار وب

  • thinking و output_config.effort برای استدلال کار می‌کنند. امضای بلوک‌های فکر فقط برای همان مدل معتبر است؛ بلوک‌ها را همان‌طور که گرفتید پس بفرستید.
  • نشانگر cache_control پذیرفته می‌شود؛ کش پرامپت را ببینید.
  • از ابزارهای سمت سرور فقط web_search_* پذیرفته می‌شود و فقط روی مدلی که قیمت جست‌وجوی وب دارد. هر جست‌وجو جدا حساب می‌شود و سقف max_uses (پیش‌فرض 5) از قبل نگه داشته می‌شود. ابزار سمت سرور دیگر 400 server_tool_unsupported می‌دهد.

هزینهٔ درخواست غیر استریم در هدر x-1ai-credits می‌آید. در استریم، هزینه در رویدادها گزارش نمی‌شود.

نمونه‌ها

curl https://1ai.ir/v1/messages \
  -H "x-api-key: $ONEAI_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "anthropic/claude-sonnet-5.5",
  "max_tokens": 300,
  "system": "You are a concise assistant.",
  "messages": [
    {
      "role": "user",
      "content": "Give me one tip for writing readable code."
    }
  ]
}'
200پاسخ
{
  "id": "msg_4f9c2b7a1e0d4c3b8a6e5d2f1c0b9a87",
  "type": "message",
  "role": "assistant",
  "model": "anthropic/claude-sonnet-5.5",
  "content": [
    {
      "type": "text",
      "text": "Name things for what they mean, not for how they are used: a clear name removes the need for a comment."
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 24,
    "output_tokens": 26,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

هدرها

  • x-api-keystringالزامی

    کلید API شما. به‌جای آن Authorization: Bearer هم پذیرفته می‌شود.

  • anthropic-versionstring

    نسخهٔ قالب، مثل 2023-06-01. SDK خودش می‌فرستد.

  • anthropic-betastring

    ویژگی‌های آزمایشی Anthropic. هدرهای anthropic-* به مدل‌هایی که قالب Anthropic را مستقیم می‌فهمند همان‌طور که فرستاده‌اید می‌رسند.

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

  • modelstringالزامی

    نام کامل مدل، مثل anthropic/claude-sonnet-5.5، یا نام Anthropic مثل claude-sonnet-5-5.

  • max_tokensintegerالزامی

    سقف توکن خروجی، از 1 تا 10,000,000. در این قالب الزامی است.

  • messagesarrayالزامی

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

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

      نقش فرستنده.

      مقادیر مجاز:userassistantsystem
    • contentstring | arrayالزامی

      متن، یا آرایه‌ای از بلوک‌ها: text، image (منبع base64 یا url)، document (PDF به‌صورت base64 یا متن)، tool_use، tool_result، thinking و redacted_thinking. هر بلوک می‌تواند cache_control داشته باشد.

  • systemstring | array

    دستور سیستمی، متن یا آرایه‌ای از بلوک‌های text.

  • streambooleanپیش‌فرض: false

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

  • toolsarray

    ابزارها، حداکثر 1024 مورد. ابزار سفارشی name، description و input_schema دارد. از ابزارهای سرور فقط web_search_* پذیرفته می‌شود.

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

      نام ابزار، حداکثر 200 نویسه.

    • descriptionstring

      توضیح کار ابزار.

    • input_schemaobject

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

  • tool_choiceobject

    { "type": "auto" }، any، none یا { "type": "tool", "name": "..." }. با disable_parallel_tool_use: true از چند ابزار هم‌زمان جلوگیری می‌شود.

  • temperaturenumber

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

  • top_pnumber

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

  • stop_sequencesarray

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

  • thinkingobject

    روشن کردن فکر کردن: { "type": "enabled", "budget_tokens": 4000 }، adaptive یا disabled. بودجهٔ بالای 16,000 استدلال زیاد و از 4000 استدلال متوسط می‌شود.

  • output_configobject

    effort (low، medium، high، xhigh، max) برای میزان استدلال و format با { "type": "json_schema", "schema": { ... } } برای خروجی ساختاریافته.

خطاها

  • invalid_request_error400

    بدنه نادرست است؛ مثلاً max_tokens یا messages نیامده یا ابزار سرور پشتیبانی‌نشده فرستاده‌اید (server_tool_unsupported).

  • authentication_error401

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

  • billing_error402

    اعتبار کافی نیست.

  • permission_error403

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

  • not_found_error404

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

  • request_too_large413

    بدنهٔ درخواست از 25 مگابایت بزرگ‌تر است.

  • rate_limit_error429

    به سقف نرخ رسیده‌اید.

  • overloaded_error529

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

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