نمای کلی

Endpointها

هر endpoint زیر یک base URL قرار دارد و از طریق HTTPS ارائه می‌شود.

https://api.shannon-ai.com

سه endpointی که متن تولید می‌کنند به همان مدل‌ها می‌رسند. endpointی را انتخاب کنید که کد شما از قبل فرمتش را به کار می‌برد.

مبانی درخواست

• بدنه هر POST یک شیء JSON است، تا 32 MiB.
• فیلدی که API نمی‌شناسد خطا ایجاد نمی‌کند و اثری ندارد. درخواستی که برای ارائه‌دهنده دیگری نوشته شده به‌خاطر یک فیلد اضافه شکست نمی‌خورد.
• فیلد شناخته‌شده‌ای با نوع JSON نادرست، یا فیلد الزامی‌ای که وجود ندارد، با 422 پاسخ داده می‌شود. بدنه‌ای که JSON معتبر نیست با 400 پاسخ داده می‌شود.
• model یکی از شناسه‌های «مدل‌ها و قیمت‌ها» است. حروف بزرگ و کوچک اهمیتی ندارند.

پاسخ JSON است، یا وقتی درخواست stream را true بگذارد، جریانی از server-sent events. هر endpoint با فرمت خودش پاسخ می‌دهد. هر پاسخ هدر x-request-id دارد.

درخواست از چه بررسی‌هایی می‌گذرد

هر درخواست پیش از اجرای مدل با ترتیبی ثابت بررسی می‌شود. اولین بررسی‌ای که شکست بخورد پاسخ می‌دهد، پس 401 هنوز چیزی درباره بدنه نمی‌گوید.

شکل خطا

خطا یک شیء JSON است که errorای دارد با type و message. /v1/messages آن را همان‌طور که SDKهای Anthropic انتظار دارند بسته‌بندی می‌کند؛ هر مسیر دیگر شکل OpenAI را به کار می‌برد.

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: gpt-4o"
  }
}

• type و message را بخوانید. code و param فقط روی برخی خطاها وجود دارند: آن‌ها را اختیاری در نظر بگیرید. param همیشه null است.
• پس از شروع stream، وضعیت از قبل 200 است. شکست آن‌گاه به‌صورت یک فریم خطا داخل stream می‌رسد.
• هر پاسخ خطا هدر x-request-id را دارد.

مدیریت خطا

صورت‌حساب و موجودی

• برای هر حساب یک موجودی وجود دارد و چت و API آن را مشترک دارند: ابتدا سهمیه روزانه پلن امروز، سپس اعتبار خریداری‌شده. API سهمیه مخصوص خود را ندارد.
• درخواست بودجه خروجی خود را (max_tokens، پیش‌فرض 4,096) رزرو می‌کند و سپس برای توکن‌هایی که واقعاً مصرف کرده، با قیمت مدل، محاسبه می‌شود.
• هر پاسخ تعداد توکن‌هایش را در usage گزارش می‌کند. صفحه «کلیدها و مصرف» موجودی و هزینه هر درخواست را نشان می‌دهد.
• هر درخواست به‌طور برابر پاسخ داده می‌شود. تنها محدودیت نرخ درخواست، محافظت در برابر هجوم درخواست است: 120 درخواست در دقیقه برای هر حساب. درخواست‌هایی که موازی فرستاده شوند در صف منتظر می‌مانند.

محدودیت‌ها و موجودی مدل‌ها و قیمت‌ها کلیدها و مصرف

فیلدهایی که به مدل بستگی دارند

هر مدل همان درخواست را می‌پذیرد. چند فیلد فقط روی برخی مدل‌ها اثر دارند؛ جدول می‌گوید کجا. صفحه‌های endpoint هر فیلد را فهرست می‌کنند.

Chat Completions

اگر از SDK مربوط به OpenAI می‌آیید

• base URL را روی https://api.shannon-ai.com/v1 و کلید را روی کلید Shannon خود بگذارید. فراخوانی‌های Chat Completions و Responses آن‌گاه با SDK همان‌طور که هست کار می‌کنند.
• model باید شناسه Shannon باشد. نام مدلِ ارائه‌دهنده دیگر، مانند gpt-4o، با 400 و unknown model پاسخ داده می‌شود.
• استدلال در فیلد جداگانه‌ای می‌آید: reasoning_content در کنار content، در پیام و در deltaهای stream.
• stream همیشه usage را در آخرین chunk خود، همراه finish_reason، دارد.
• فراخوانی ابزار در stream به‌صورت یک chunk با رشته کامل arguments می‌رسد.
• پاسخ یک choice دارد.
• مسیرهای API مربوط به OpenAI که در جدول بالا نیستند، مانند /v1/embeddings، با 404 پاسخ داده می‌شوند.

اگر از SDK مربوط به Anthropic می‌آیید

• base URL را روی https://api.shannon-ai.com بگذارید، بدون /v1، و کلید را روی کلید Shannon خود. SDK آن را به‌صورت x-api-key می‌فرستد.
• model باید شناسه Shannon باشد.
• max_tokens در این API اختیاری است. مقدار پیش‌فرض آن 4,096 است.
• پاسخ شامل بلوک‌های محتوا از نوع thinking، text و tool_use است. بلوک اول همیشه متن نیست: بلوک‌ها را از روی type انتخاب کنید.
• stop_reason برابر end_turn یا tool_use است. stream مدل Shannon می‌تواند با max_tokens هم پایان یابد.
• anthropic-version و anthropic-beta پذیرفته می‌شوند، پس SDK بدون تغییر کار می‌کند. درخواست به آن‌ها نیاز ندارد.
• خطاها روی /v1/messages شکل Anthropic را دارند: {"type": "error", "error": {…}}.

ابزارهای کدنویسی که با این فرمت‌ها کار می‌کنند به همین شکل تنظیم می‌شوند: base URL، کلید و یک شناسه Shannon به‌عنوان مدل. ابزارهای CLI برای کدنویسی