رفتن به محتوای اصلی
هوشوانا

Anthropic Messages API

فراخوانی مدل‌های Claude با API سازگار با Anthropic در هوشوانا: هدرها، cURL، SDK پایتون و TypeScript، استریم رویدادها و فراخوانی ابزار.

آخرین به‌روزرسانی:

هوشوانا علاوه بر API سازگار با OpenAI، endpoint سازگار با Anthropic Messages API را هم ارائه می‌کند. این همان API است که SDKهای رسمی Anthropic و ابزارهایی مثل Claude Code استفاده می‌کنند. هدف اصلی این endpoint مدل‌های Claude است. برای مدل‌های سایر ارائه‌دهنده‌ها از Chat Completions استفاده کنید.

POST https://hooshvana.ir/api/v1/messages

آدرس پایه برای SDKهای Anthropic

SDKهای Anthropic خودشان مسیر /v1/messages را به آدرس پایه اضافه می‌کنند. بنابراین در SDK از آدرس زیر (بدون /v1) استفاده کنید:

https://hooshvana.ir/api

اگر مستقیم با cURL یا HTTP کار می‌کنید، از آدرس کامل https://hooshvana.ir/api/v1/messages استفاده کنید.

هدرها

هدرمقدارتوضیح
x-api-keyhv-...کلید هوشوانا. Authorization: Bearer هم پذیرفته می‌شود
anthropic-version2023-06-01نسخه‌ی API، مطابق مستندات Anthropic
content-typeapplication/jsonالزامی

شناسه‌ی مدل‌ها

مدل‌های Claude با پیشوند anthropic/ شناخته می‌شوند، مثلاً anthropic/claude-sonnet-4.6 و anthropic/claude-haiku-4.5. این شناسه‌ها نمونه‌اند. فهرست به‌روز را در کاتالوگ مدل‌ها ببینید.

درخواست با cURL

Shell
curl https://hooshvana.ir/api/v1/messages \
  -H "x-api-key: $HOOSHVANA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "max_tokens": 1024,
    "system": "You are a helpful assistant. Reply in Persian.",
    "messages": [
      {"role": "user", "content": "یک برنامه‌ی مطالعه‌ی یک‌هفته‌ای برای یادگیری SQL پیشنهاد بده."}
    ]
  }'

برخلاف Chat Completions، در Messages API فیلد max_tokens الزامی است و دستور سیستمی در فیلد جداگانه‌ی system قرار می‌گیرد، نه در آرایه‌ی پیام‌ها.

نمونه‌ی پاسخ:

JSON
{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "model": "anthropic/claude-sonnet-4.6",
  "content": [{ "type": "text", "text": "روز اول: آشنایی با SELECT و WHERE..." }],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 52, "output_tokens": 410 }
}

Python با SDK رسمی Anthropic

Shell
pip install anthropic
Python
import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://hooshvana.ir/api",
    api_key=os.environ["HOOSHVANA_API_KEY"],
)

message = client.messages.create(
    model="anthropic/claude-sonnet-4.6",
    max_tokens=1024,
    system="You are a helpful assistant. Reply in Persian.",
    messages=[{"role": "user", "content": "مفهوم بازگشت (recursion) را با یک مثال ساده توضیح بده."}],
)

print(message.content[0].text)
print(message.usage)

TypeScript با @anthropic-ai/sdk

Shell
npm install @anthropic-ai/sdk
TypeScript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://hooshvana.ir/api",
  apiKey: process.env.HOOSHVANA_API_KEY,
});

const message = await client.messages.create({
  model: "anthropic/claude-haiku-4.5",
  max_tokens: 512,
  messages: [{ role: "user", content: "سه ایده برای نام یک استارتاپ آموزشی بده." }],
});

for (const block of message.content) {
  if (block.type === "text") console.log(block.text);
}

استریم

با "stream": true پاسخ به صورت رویدادهای SSE نام‌دار می‌آید:

رویدادمعنی
message_startشروع پیام، شامل شیء پیام اولیه و usage ورودی
content_block_startشروع یک بلوک محتوا (متن یا tool_use)
content_block_deltaتکه‌ی جدید؛ برای متن از نوع text_delta و برای ابزار از نوع input_json_delta
content_block_stopپایان بلوک
message_deltaتغییرات نهایی مثل stop_reason و usage خروجی
message_stopپایان پیام

SDKها کار با این رویدادها را ساده کرده‌اند:

Python
with client.messages.stream(
    model="anthropic/claude-sonnet-4.6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "یک شعر کوتاه درباره‌ی پاییز تهران بنویس."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

    final = stream.get_final_message()
    print()
    print("output tokens:", final.usage.output_tokens)
TypeScript
const stream = client.messages.stream({
  model: "anthropic/claude-sonnet-4.6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "یک شعر کوتاه درباره‌ی پاییز تهران بنویس." }],
});

stream.on("text", (text) => process.stdout.write(text));
const final = await stream.finalMessage();
console.log("\noutput tokens:", final.usage.output_tokens);

فراخوانی ابزار

ابزارها با name، description و input_schema تعریف می‌شوند. وقتی مدل بخواهد ابزاری را صدا بزند، stop_reason برابر tool_use می‌شود و یک بلوک tool_use در محتوا می‌آید. نتیجه را با یک بلوک tool_result در پیام کاربر برمی‌گردانید:

Python
tools = [{
    "name": "get_exchange_rate",
    "description": "Get the latest exchange rate between two currencies.",
    "input_schema": {
        "type": "object",
        "properties": {
            "base": {"type": "string"},
            "quote": {"type": "string"},
        },
        "required": ["base", "quote"],
    },
}]

messages = [{"role": "user", "content": "نرخ یورو به دلار چند است؟"}]

first = client.messages.create(
    model="anthropic/claude-sonnet-4.6",
    max_tokens=1024,
    tools=tools,
    messages=messages,
)

if first.stop_reason == "tool_use":
    tool_use = next(b for b in first.content if b.type == "tool_use")
    result = {"rate": 1.08}  # call your real service with tool_use.input

    messages.append({"role": "assistant", "content": first.content})
    messages.append({
        "role": "user",
        "content": [{
            "type": "tool_result",
            "tool_use_id": tool_use.id,
            "content": str(result),
        }],
    })

    final = client.messages.create(
        model="anthropic/claude-sonnet-4.6",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    print(final.content[0].text)

Claude Code

Claude Code از همین endpoint استفاده می‌کند. با تنظیم دو متغیر محیطی ANTHROPIC_BASE_URL و ANTHROPIC_AUTH_TOKEN (یا ANTHROPIC_API_KEY) می‌توانید آن را به هوشوانا وصل کنید. راهنمای کامل در اتصال Claude Code آمده است.

نکته‌ها

  • هزینه بر اساس input_tokens و output_tokens در usage محاسبه می‌شود. جزئیات در قیمت‌گذاری.
  • خطاها در این endpoint هم با کدهای هوشوانا برمی‌گردند (مثل insufficient_balance یا model_not_allowed). جدول کامل در خطاها و کدها.
  • اگر کد شما به هر دو قالب نیاز دارد، می‌توانید با یک کلید هم از /messages و هم از /chat/completions استفاده کنید، مگر این‌که در قوانین کلید یکی را محدود کرده باشید.