Преглед

Ендпоинти

Всеки ендпоинт е под един базов URL и се обслужва през HTTPS.

https://api.shannon-ai.com

Трите ендпоинта, които създават текст, стигат до едни и същи модели. Изберете този, чийто формат вашият код вече използва.

Основи на заявките

• Тялото на всяка POST заявка е един JSON обект, до 32 MiB.
• Поле, което API не познава, не причинява грешка и няма ефект. Заявка, написана за друг доставчик, не се проваля заради допълнително поле.
• Познато поле с грешен JSON тип или липсващо задължително поле получава отговор 422. Тяло, което не е валиден JSON, получава отговор 400.
• model е едно от id-тата на Models & pricing. Главните и малките букви нямат значение.

Отговорът е JSON или стрийм от server-sent events, когато заявката задава stream на true. Всеки ендпоинт отговаря в собствения си формат. Всеки отговор има хедъра 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.
• След като стрийм е започнал, статусът вече е 200. Тогава неуспехът пристига като кадър за грешка в стрийма.
• Всеки отговор с грешка носи хедъра x-request-id.

Обработка на грешки

Фактуриране и баланс

• Има един баланс на акаунт и чатът и API го споделят: първо днешният лимит на плана, после закупеният кредит. API няма собствена квота.
• Заявката резервира своя изходен бюджет (max_tokens, по подразбиране 4,096) и след това се таксува за токените, които действително е използвала, по цената на модела.
• Всеки отговор докладва броя си токени в usage. Страницата Keys & usage показва баланса и колко е струвала всяка заявка.
• Всяка заявка се обслужва еднакво. Единственото ограничение на честотата на заявките е защитата от наводняване: 120 заявки в минута на акаунт. Заявките, изпратени паралелно, чакат на опашка.

Ограничения и баланс Модели и цени Keys & usage

Полета, които зависят от модела

Всеки модел приема една и съща заявка. Някои полета имат ефект само при определени модели; таблицата посочва къде. Страниците на ендпоинтите изброяват всяко поле.

Chat Completions

Ако идвате от SDK на OpenAI

• Задайте базовия URL на https://api.shannon-ai.com/v1, а ключа на Вашия ключ за Shannon. Тогава извикванията на Chat Completions и Responses работят със SDK такъв, какъвто е.
• model трябва да е id на Shannon. Име на модел на друг доставчик, например gpt-4o, получава отговор 400 и unknown model.
• Разсъжденията идват в отделно поле: reasoning_content до content, в съобщението и в делтите на стрийма.
• Стриймът винаги носи usage в последния си фрагмент, заедно с finish_reason.
• Извикване на инструмент в стрийм пристига като един фрагмент с пълния низ arguments.
• Отговорът има един избор.
• Пътища на API на OpenAI, които не са в таблицата по-горе, например /v1/embeddings, получават отговор 404.

Ако идвате от SDK на Anthropic

• Задайте базовия URL на https://api.shannon-ai.com, без /v1, а ключа на Вашия ключ за Shannon. SDK го изпраща като x-api-key.
• model трябва да е id на Shannon.
• max_tokens е по избор в това API. Стойността му по подразбиране е 4,096.
• Отговорът съдържа блокове със съдържание от тип thinking, text и tool_use. Първият блок не винаги е текстът: избирайте блоковете по type.
• stop_reason е end_turn или tool_use. Стрийм на модел на Shannon може да завърши и с max_tokens.
• anthropic-version и anthropic-beta се приемат, така че SDK работи без промяна. Заявката не се нуждае от тях.
• Грешките на /v1/messages имат формата на Anthropic: {"type": "error", "error": {…}}.

Инструментите за програмиране, които говорят тези формати, се настройват по същия начин: базов URL, ключ и id на Shannon като модел. CLI инструменти за програмиране