Messages API

Messages API قرارداد بومی Anthropic برای کار با مدل‌های Claude است. این صفحه کمک می‌کند بفهمید چه زمانی به این قرارداد نیاز دارید و چه زمانی بهتر است از مسیر عمومی‌تر Chat Completions در گدارAI استفاده کنید.

جایگاه Messages API در گدارAI

گدارAI مدل‌های Anthropic را هم از مسیر سازگار با OpenAI و هم از مسیر بومی Anthropic عرضه می‌کند. مسیر POST /v1/messages درخواست و پاسخ Anthropic را حفظ می‌کند؛ مسیر POST /v1/chat/completions همان قابلیت‌ها را تا حد ممکن به قرارداد OpenAI نگاشت می‌کند.

قاعده انتخاب:

• اگر چند ارائه‌دهنده مدل دارید و می‌خواهید قرارداد واحد داشته باشید، از Chat Completions شروع کنید.
• اگر اپلیکیشن شما به شکل دقیق پاسخ‌ها و قابلیت‌های اختصاصی Claude وابسته است، Messages API را بررسی کنید.
• اگر باید ساختار بومی Anthropic را حفظ کنید، از /v1/messages استفاده کنید.

Messages API چه مسئله‌ای را حل می‌کند؟

این API برای تیم‌هایی مفید است که:

• قبلاً با SDK رسمی Anthropic کار کرده‌اند.
• ساختار پیام‌ها و پاسخ‌های Claude را در اپلیکیشن خود نگه داشته‌اند.
• می‌خواهند از قابلیت‌هایی استفاده کنند که در قرارداد بومی Anthropic روشن‌تر بیان می‌شوند.
• هنگام مهاجرت به گدارAI، کمترین تغییر را در لایه مصرف Anthropic داشته باشند.

شکل رایج درخواست

درخواست بومی معمولاً با این فیلدها ساخته می‌شود:

• model
• max_tokens
• system
• messages

نمونه مفهومی:

Python

import requests

response = requests.post(
    "https://YOUR_WORKSPACE.godarai.ir/v1/messages",
    headers={
        "Authorization": "Bearer YOUR_GODARAI_TOKEN",
        "Content-Type": "application/json",
        "anthropic-version": "2023-06-01",
    },
    json={
  "model": "anthropic:default:claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "You are a concise Persian technical assistant.",
  "messages": [
    {
      "role": "user",
      "content": "معماری درگاه مدل‌های زبانی را ساده توضیح بده."
    }
  ]
},
    timeout=60,
)

response.raise_for_status()
print(response.json())

NodeJS

const response = await fetch("https://YOUR_WORKSPACE.godarai.ir/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_GODARAI_TOKEN",
    "Content-Type": "application/json",
    "anthropic-version": "2023-06-01",
  },
  body: JSON.stringify({
  "model": "anthropic:default:claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "You are a concise Persian technical assistant.",
  "messages": [
    {
      "role": "user",
      "content": "معماری درگاه مدل‌های زبانی را ساده توضیح بده."
    }
  ]
}),
});

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

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

REST API

curl --request POST "https://YOUR_WORKSPACE.godarai.ir/v1/messages" \
  --header "Authorization: Bearer YOUR_GODARAI_TOKEN" \
  --header "Content-Type: application/json" \
  --header "anthropic-version: 2023-06-01" \
  --data '{
  "model": "anthropic:default:claude-sonnet-4-6",
  "max_tokens": 1024,
  "system": "You are a concise Persian technical assistant.",
  "messages": [
    {
      "role": "user",
      "content": "معماری درگاه مدل‌های زبانی را ساده توضیح بده."
    }
  ]
}'

توکن گدارAI را در Authorization: Bearer یا x-api-key بفرستید. گدارAI این توکن را فقط برای احراز هویت درخواست مصرف می‌کند و آن را به Anthropic نمی‌فرستد.

هشدار

برای جلوگیری از انتخاب حساب اشتباه، در محیط‌های چندحسابی شناسه کامل مدل را بفرستید. شناسه ساده فقط زمانی پذیرفته می‌شود که دقیقاً به یک حساب Anthropic مجاز برسد؛ در غیر این صورت پاسخ ambiguous_provider_account دریافت می‌کنید.

مسیرهای بومی در دسترس

• POST /v1/messages برای ساخت پیام همگام یا جریانی
• POST /v1/messages/count_tokens برای شمارش توکن
• خانواده /v1/messages/batches برای ساخت، پیگیری، لغو و دریافت نتیجه دسته‌ها
• خانواده /v1/files برای بارگذاری، فهرست، دریافت و حذف فایل‌ها
• GET /v1/models و GET /v1/models/{id} برای فهرست و جزئیات مدل‌ها

در مسیرهای مشترک /v1/models و /v1/files، سرآیند anthropic-version قرارداد بومی Anthropic را انتخاب می‌کند. بدون این سرآیند، رفتار سازگار با OpenAI همان مسیر حفظ می‌شود.

تفاوت با Chat Completions

موضوع	Chat Completions	Messages API
هدف	قرارداد واحد برای چند ارائه‌دهنده	قرارداد بومی Anthropic
ساختار ورودی	messages با نقش‌های سازگار با OpenAI	system جدا و messages به سبک Anthropic
مناسب برای	محصولات چندمدلی و مهاجرت ساده‌تر	محصولات Claude-first
ریسک قفل‌شدن به یک قرارداد	کمتر	بیشتر، اما کنترل بومی‌تر

نکته آموزشی: اگر محصول شما از ابتدا چندمدلی است، به شکل پاسخ یک ارائه‌دهنده قفل نشوید. یک لایه کوچک در اپلیکیشن خود بسازید که پاسخ مدل را به شکل داخلی محصول شما تبدیل کند.

پاسخ مورد انتظار

پاسخ بومی، بلوک‌های متن، ابزار، تفکر، تفکر پوشیده و ارجاع را بدون تبدیل به شکل OpenAI برمی‌گرداند. نمونه ساده:

{
  "id": "msg_123",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "درگاه مدل‌های زبانی یک لایه کنترل‌شده بین اپلیکیشن شما و ارائه‌دهنده‌های مدل است."
    }
  ],
  "model": "claude-3-5-sonnet",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 22,
    "output_tokens": 64
  }
}

برای تحلیل هزینه و رفتار، usage و request-id را ذخیره و با گزارش رخدادهای گدارAI تطبیق دهید. در پاسخ جریانی، خطای میانه جریان به‌صورت خطا باقی می‌ماند و با پایان موفق کاذب پوشانده نمی‌شود.

پیش از استفاده چه چیزهایی را بررسی کنم؟

• آیا مدل Anthropic انتخابی در دسترسی شما مجاز است؟
• آیا اپلیکیشن شما واقعاً به شکل پاسخ Anthropic نیاز دارد یا Chat Completions کافی است؟
• آیا توکن مصرفی برای سرویس محیط عملیاتی از نوع کلید دسترسی مجازی است؟
• آیا قابلیت آزمایشی درخواستی در فهرست مجاز همان حساب Anthropic قرار دارد؟

جمع‌بندی

Messages API برای تیم‌های Claude-first ارزشمند است، اما برای اتصال‌های چندمدلی، Chat Completions قرارداد یکدست‌تری می‌دهد. تصمیم را بر اساس قرارداد اپلیکیشن و مدل‌های مجاز بگیرید.