سازگاری با OpenAI و Anthropic

سه راه برای اتصال

ساروی یک حساب، کلید پروژه و سیستم اعتبار دارد. قالب OpenAI یا Anthropic فقط روش ارسال و دریافت درخواست را عوض می‌کند. در هر دو از کلید ساروی و شناسهٔ مدل‌های فهرست مدل‌ها استفاده کنید.

کلاینت OpenAI

آدرس پایه https://api.sarovi.ir/v1 است. شروع سریع نمونهٔ کامل دارد. نگهداری conversation با previous_response_id و همهٔ ابزارهای میزبانی‌شدهٔ OpenAI پشتیبانی نمی‌شوند؛ فقط فیلدهای مرجع ساروی را ارسال کنید.

کلاینت Anthropic

import os
from anthropic import Anthropic
client = Anthropic(
    api_key=os.environ["SAROVI_API_KEY"],
    base_url="https://api.sarovi.ir",
    max_retries=0,
)
message = client.messages.create(
    model="anthropic/claude-opus-5.5",
    max_tokens=512,
    messages=[{"role": "user", "content": "سلام!"}],
)
for block in message.content:
    if block.type == "text":
        print(block.text)

با pip install anthropic نصب کنید. در TypeScript بستهٔ @anthropic-ai/sdk را نصب و baseURL را روی https://api.sarovi.ir تنظیم کنید. کلاینت هدرهای x-api-key و anthropic-version: 2023-06-01 را می‌فرستد. دسترسی responses:write لازم است. شناسه‌های کوتاه یا aliasهای مدل Anthropic خودکار تبدیل نمی‌شوند.

ابزار و streaming در Messages

ابزار با name، description و input_schema تعریف می‌شود. پاسخ tool_use شامل id، name و input است. برنامه ابزار را اجرا می‌کند و نتیجه را با tool_result و همان tool_use_id در پیام user برمی‌گرداند. تمام نتیجه‌های ابزار را پیش از پیام بعدی ارسال کنید.

stream=true رویدادهای message_start، content_block_start، content_block_delta، content_block_stop، message_delta و message_stop را برمی‌گرداند. خطای میان جریان با event: error اعلام می‌شود؛ به message_stop برای پایان موفق توجه کنید.

تصویر در Messages

در پیام user و نتیجهٔ ابزار می‌توانید بلوک image بفرستید. source از نوع url با آدرس HTTPS یا base64 با media_type برابر image/jpeg، image/png، image/gif یا image/webp پذیرفته می‌شود. مدل باید ورودی image داشته باشد؛ در غیر این صورت درخواست پیش از رزرو اعتبار رد می‌شود. سقف کل درخواست ۴ MB و هر تصویر base64 حداکثر ۲٬۸۰۰٬۰۰۰ نویسه است. آدرس و دادهٔ تصویر در پیش‌نمایش گزارش ذخیره نمی‌شوند.

Thinking و prompt caching

برای Claude مقدار thinking را به {"type":"enabled","budget_tokens":1024} و max_tokens را بیشتر از بودجهٔ thinking بگذارید. مدل‌های دارای adaptive thinking مقدار {"type":"adaptive"} را می‌پذیرند. پشتیبانی به مدل وابسته است. بلوک‌های thinking، redacted_thinking و signature را در ادامهٔ گفتگو بدون تغییر برگردانید؛ جریان نیز thinking_delta و signature_delta را حفظ می‌کند.

cache_control با type برابر ephemeral و ttl برابر 5m یا 1h روی درخواست، بلوک متن، تصویر، سند و تعریف ابزار پذیرفته می‌شود. کش به حداقل طول ورودی و قابلیت مدل وابسته است؛ هر درخواست الزاماً cache hit ندارد. usage شمارنده‌های cache_creation_input_tokens و cache_read_input_tokens را جداگانه برمی‌گرداند. هزینهٔ نوشتن و خواندن کش در تسویهٔ اعتبار لحاظ می‌شود.

message = client.messages.create(
    model="anthropic/claude-sonnet-4.5",
    max_tokens=2048,
    thinking={"type": "enabled", "budget_tokens": 1024},
    system=[{"type": "text", "text": long_context,
             "cache_control": {"type": "ephemeral", "ttl": "5m"}}],
    messages=[{"role": "user", "content": "این متن را تحلیل کن."}],
)

سند و PDF

بلوک document در پیام user یا tool_result، PDF از HTTPS یا base64، متن text/plain و محتوای ترکیبی متن و تصویر را می‌پذیرد. برای PDF بومی، مدل دارای ورودی تصویر انتخاب کنید. citations.enabled ارجاع‌های مدل را فعال می‌کند و پاسخ آن‌ها بدون تبدیل برمی‌گردد. سقف کل درخواست ۴ MB و هر فایل base64 حداکثر ۲٬۸۰۰٬۰۰۰ نویسه است. فایل‌های بزرگ‌تر را با URL عمومی HTTPS بفرستید. شناسهٔ فایل یا container متعلق به ارائه‌دهنده پذیرفته نمی‌شود.

messages = [{"role": "user", "content": [
    {"type": "document", "source": {"type": "url", "url": pdf_url},
     "citations": {"enabled": True}},
    {"type": "text", "text": "نکات اصلی را با ارجاع بنویس."},
]}]

ابزارهای میزبانی‌شده

web_search_20250305 و web_search_20260209 با name برابر web_search و max_uses بین ۱ تا ۵ پذیرفته می‌شوند. web_fetch_20250910 با name برابر web_fetch، حداکثر ۵ استفاده و max_content_tokens تا ۳۲٬۰۰۰ قابل تنظیم است. مدل و ارائه‌دهنده باید این ابزار را پشتیبانی کنند.

ابزارهای openrouter:web_search، openrouter:web_fetch، openrouter:datetime و openrouter:bash نیز در Messages پذیرفته می‌شوند. bash در محیط جداگانهٔ ارائه‌دهنده اجرا می‌شود؛ شناسهٔ container مشترک پذیرفته نیست. حلقهٔ ابزار به ۵ مرحله محدود است. نتیجه‌های server_tool_use و ابزارهای سرور در پاسخ و ادامهٔ گفتگو حفظ می‌شوند. هزینهٔ ابزار و توکن در حسابداری مصرف می‌آید.

message = client.messages.create(
    model="anthropic/claude-haiku-4.5", max_tokens=512,
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 1}],
    messages=[{"role": "user", "content": "تغییرات اخیر Python را جستجو کن."}],
)

Computer use

computer_20250124 و computer_20251124 با name برابر computer و display_width_px و display_height_px پشتیبانی می‌شوند. هدر متناظر computer-use-2025-01-24 یا computer-use-2025-11-24 را در anthropic-beta بفرستید. مدل Claude سازگار انتخاب کنید.

ساروی تعریف computer را به ابزار سفارشی با قرارداد action تبدیل می‌کند؛ این مسیر معادل ابزار بومی Anthropic در سمت ارائه‌دهنده نیست. این ابزار در برنامهٔ شما اجرا می‌شود: مدل tool_use می‌دهد، برنامهٔ شما عمل را در محیط خودش انجام می‌دهد و screenshot یا نتیجه را با tool_result برمی‌گرداند. ساروی دسکتاپ یا مرورگر شما را خودکار کنترل نمی‌کند. bash_20250124 و ابزار text_editor نیز همین چرخهٔ سمت کلاینت را دارند.

پردازش گروهی Messages

کلاینت رسمی Anthropic می‌تواند از create، retrieve، list، cancel و results در /v1/messages/batches استفاده کند. هر ردیف custom_id یکتا و params با قرارداد Messages دارد؛ stream=false است. حداکثر ۱۰۰۰ ردیف و سقف کل درخواست ۴ MB است. ایجاد و لغو به responses:write و خواندن به usage:read نیاز دارد.

batch = client.messages.batches.create(requests=[{
    "custom_id": "item-1",
    "params": {"model": "anthropic/claude-haiku-4.5", "max_tokens": 128,
               "messages": [{"role": "user", "content": "سلام!"}]},
}])
# همان شناسه را بررسی کنید؛ برای بررسی وضعیت، batch تازه نسازید.
batch = client.messages.batches.retrieve(batch.id)
if batch.processing_status == "ended":
    for result in client.messages.batches.results(batch.id):
        print(result.custom_id, result.result.type)

کار در صف ماندگار ساروی اجرا می‌شود؛ تخفیف ۵۰٪ یا زمان‌بندی Anthropic Batch را وعده نمی‌دهد. هزینهٔ هر ردیف با نرخ عادی مصرف واقعی تسویه می‌شود. سقف داخلی کل batch از رزروهای ردیف‌ها محاسبه می‌شود؛ موجودی حساب و محدودیت کلید همچنان اعمال می‌شوند. لغو، ردیف‌های شروع‌نشده را متوقف می‌کند؛ درخواست در حال اجرا ممکن است کامل و محاسبه شود. نتایج JSONL تا expires_at قابل دریافت‌اند. نتیجهٔ مبهم خودکار دوباره اجرا نمی‌شود.

شمارش توکن و محدودیت‌ها

شمارش دقیق /v1/messages/count_tokens در این انتشار فعال نیست؛ HTTP 503 با توضیح روشن می‌دهد، هیچ generation شروع نمی‌کند و اعتبار مصرف نمی‌شود. تخمین محلی به‌جای شمارش دقیق برگردانده نمی‌شود.

فیلدهای خارج از قرارداد با خطای روشن رد می‌شوند. این سازگاری به معنی پشتیبانی از همهٔ ویژگی‌های Anthropic یا همهٔ برنامه‌های Claude Code نیست. مرجع API قرارداد دقیق این انتشار را نشان می‌دهد.