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-key | hv-... | کلید هوشوانا. Authorization: Bearer هم پذیرفته میشود |
anthropic-version | 2023-06-01 | نسخهی API، مطابق مستندات Anthropic |
content-type | application/json | الزامی |
شناسهی مدلها
مدلهای Claude با پیشوند anthropic/ شناخته میشوند، مثلاً anthropic/claude-sonnet-4.6 و anthropic/claude-haiku-4.5. این شناسهها نمونهاند. فهرست بهروز را در کاتالوگ مدلها ببینید.
درخواست با cURL
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 قرار میگیرد، نه در آرایهی پیامها.
نمونهی پاسخ:
{
"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
pip install anthropicimport 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
npm install @anthropic-ai/sdkimport 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ها کار با این رویدادها را ساده کردهاند:
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)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 در پیام کاربر برمیگردانید:
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استفاده کنید، مگر اینکه در قوانین کلید یکی را محدود کرده باشید.