Create a message

یک پیام را با فرمت Anthropic Messages API می‌سازد؛ پشتیبانی از متن، تصویر، PDF، ابزارها و تفکر گسترده.

نقطهٔ پایانی POST /messages با همان ساختار Anthropic Messages کار می‌کند و پاسخ را به فرمت استاندارد Anthropic برمی‌گرداند. خروجی غیراستریمی یا رویدادهای جریان SSE، از طریق همین نقطهٔ پایانی در دسترس است.

درخواست‌ها به‌صورت خودکار با چندین پروایدر مسیریابی می‌شوند؛ برای دیدن مدل‌های در دسترس و ترجیحات مسیریابی می‌توانید از provider استفاده کنید.

Endpoint

                POST
                /messages
              

https://app.asha-ai.ir/v1/messages

احراز هویت

با کلید API آشا از طریق هدر Authorization: Bearer <ASHA_API_KEY> احراز هویت کنید.

هدرهای درخواست

هدر	نوع	پیش‌فرض	توضیح
`Authorization`	string	—	الزامی. کلید API به‌صورت Bearer.
`X-OpenRouter-Metadata`	enum	`disabled`	دسترسی به فرادادهٔ مسیریابی در پاسخ؛ `enabled` یا `disabled`.

پارامترهای بدنهٔ درخواست

پارامتر	نوع	پیش‌فرض	توضیح
`model`	string	—	الزامی. شناسهٔ مدل، مانند `anthropic/claude-sonnet-4`.
`messages`	array	—	الزامی. لیست پیام‌ها با `role` و `content`؛ هر پیام می‌تواند شامل متن، تصویر یا سند باشد.
`max_tokens`	integer	—	حداکثر توکن‌های خروجی.
`temperature`	number	—	کنترل میزان تصادفی بودن خروجی.
`top_p`	number	—	نمونه‌برداری هسته (نوکلئوس).
`top_k`	integer	—	محدود کردن نمونه‌برداری به تعداد مشخصی از محتمل‌ترین گزینه‌ها.
`stream`	boolean	`false`	اگر `true` باشد، پاسخ به‌صورت رویدادهای SSE ارسال می‌شود.
`system`	string \| array	—	پرامپت سیستم؛ می‌تواند رشته یا لیستی از بلوک‌های متنی با کش باشد.
`stop_sequences`	array	—	توالی‌هایی که تولید را متوقف می‌کنند.
`thinking`	object	—	تفکر گسترده: `enabled` با `budget_tokens`، `adaptive` یا `disabled`.
`tools`	array	—	ابزارهای مجاز مدل؛ شامل ابزارهای تعریف‌شده، ابزارهای سرور و ابزارهای جستجو.
`tool_choice`	object	—	نحوهٔ انتخاب ابزار: `auto`، `any`، `none` یا ابزار مشخص با `name`.
`provider`	object	—	ترجیحات مسیریابی (پروایدرهای مجاز/ممنوع، هزینهٔ بیشینه، مرتب‌سازی و…).
`metadata`	object	—	فراداده؛ شامل `user_id` برای ردیابی کاربر.
`user`	string	—	شناسهٔ کاربر نهایی برای تمایز کاربران و جلوگیری از سوءاستفاده (حداکثر ۲۵۶ نویسه).
`service_tier`	string	—	سطح خدمتِ پروایدر؛ مثل `standard`.
`models`	array	—	فهرست مدل‌ها برای مسیریابی چندمدلی؛ نمی‌تواند با `fallbacks` ترکیب شود.
`fallbacks`	array	—	مدل‌های جایگزین برای شکست مدل اصلی (حداکثر ۳ مورد؛ هر مورد فقط `model`).
`output_config`	object	—	کنترل تلاش (`effort`)، قالب خروجی (`format`) و بودجهٔ وظیفه.
`session_id`	string	—	کلید مسیریابی پایدار برای گروه‌بندی درخواست‌های مرتبط و بازدهی کش (حداکثر ۲۵۶ نویسه).
`speed`	enum	`standard`	سرعت خروجی؛ `fast` با قیمت بالاتر یا `standard`.
`cache_control`	object	—	کش خودکار پرامپت؛ در سطح درخواست یا روی بلوک‌های محتوایی.
`stop_server_tools_when`	array	—	شرط‌های توقف حلقهٔ ابزارهای سرور.
`plugins`	array	—	افزونه‌های درخواست (جستجوی وب، فشرده‌سازی زمینه، مسیریاب خودکار و…).
`trace`	object	—	فرادادهٔ ردیابی برای مشاهده‌پذیری.

مثال درخواست

curl https://app.asha-ai.ir/v1/messages 
  -H "Authorization: Bearer $ASHA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "anthropic/claude-sonnet-4",
    "max_tokens": 1024,
    "messages": [
      { "role": "user", "content": "Hello, how are you?" }
    ]
  }'

import requests

response = requests.post(
    'https://app.asha-ai.ir/v1/messages',
    headers={'Authorization': 'Bearer <ASHA_API_KEY>'},
    json={
        'model': 'anthropic/claude-sonnet-4',
        'max_tokens': 1024,
        'messages': [
            {'role': 'user', 'content': 'Hello, how are you?'}
        ],
    },
)

message = response.json()
print(message['content'][0]['text'])
print(f"usage={message['usage']}")

const response = await fetch('https://app.asha-ai.ir/v1/messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <ASHA_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'anthropic/claude-sonnet-4',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello, how are you?' }],
  }),
});

const message = await response.json();
console.log(message.content[0].text);
console.log(`usage=${JSON.stringify(message.usage)}`);

پاسخ موفق

در صورت موفقیت، پاسخ غیراستریمی با کد 200 برمی‌گردد:

                JSON
                200 OK
              

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "model": "anthropic/claude-sonnet-4",
  "content": [
    {
      "type": "text",
      "citations": [],
      "text": "I'm doing well, thank you for asking! How can I help you today?"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "stop_details": null,
  "container": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 18,
    "cache_creation_input_tokens": null,
    "cache_read_input_tokens": null,
    "cache_creation": null,
    "inference_geo": null,
    "server_tool_use": null,
    "service_tier": "standard",
    "output_tokens_details": null
  }
}

استریم

اگر stream: true ارسال کنید، پاسخ به‌صورت رویدادهای SSE با ساختار event و data ارسال می‌شود. رویدادهای ممکن:

رویداد	توضیح
`message_start`	شروع پیام؛ شامل پیام اولیه با `id` و `usage`.
`content_block_start`	شروع یک بلوک محتوایی جدید.
`content_block_delta`	افزودن محتوا به بلوک (متن، JSON ورودی ابزار، تفکر و…).
`content_block_stop`	تکمیل یک بلوک محتوایی.
`message_delta`	تغییر فرادادهٔ پیام مثل `stop_reason` و آمار توکن.
`message_stop`	پایان موفق پیام.
`error`	بروز خطا در میانهٔ جریان.

فیلدهای پاسخ

فیلد	توضیح
`id`	شناسهٔ پیام.
`type`	همیشه `message` برای پاسخ نهایی.
`role`	همیشه `assistant`.
`model`	مدلی که پیام را تولید کرده است.
`content`	لیست بلوک‌های محتوایی (متن، ابزار، تفکر و…).
`stop_reason`	دلیل توقف؛ `end_turn`، `max_tokens`، `tool_use` و….
`usage`	مصرف توکن ورودی/خروجی، کش و هزینه.

خطاها

کد	توضیح
`400`	درخواست نامعتبر (مثلاً `messages` الزامی است).
`401`	کلید API نامعتبر.
`402`	اعتبار کافی نیست؛ برای تکمیل درخواست باید موجودی افزوده شود.
`429`	سقف نرخ درخواست رد شده است.
`500`	خطای داخلی سرور.
`502`	پروایدر خطای بالادستی برگرداند.