Visão geral

Endpoints

Todos os endpoints ficam sob uma única base URL e são servidos por HTTPS.

https://api.shannon-ai.com

Os três endpoints que produzem texto chegam aos mesmos modelos. Escolha aquele cujo formato o seu código já usa.

Noções básicas de requisição

• O corpo de todo POST é um objeto JSON, de até 32 MiB.
• Um campo que a API não conhece não causa erro e não tem efeito. Uma requisição escrita para outro provedor não falha por causa de um campo extra.
• Um campo conhecido com o tipo JSON errado, ou um campo obrigatório ausente, é respondido com 422. Um corpo que não é um JSON válido é respondido com 400.
• model é um dos ids em Modelos e preços. Maiúsculas e minúsculas não importam.

Uma resposta é JSON, ou um stream de server-sent events quando a requisição define stream como true. Cada endpoint responde no seu próprio formato. Toda resposta tem o header x-request-id.

O que uma requisição atravessa

Uma requisição é verificada em uma ordem fixa antes de um modelo ser executado. A primeira verificação que falha responde, então um 401 ainda não diz nada sobre o corpo.

Formato do erro

Um erro é um objeto JSON com um error que contém type e message. /v1/messages o embrulha do modo que os SDKs da Anthropic esperam; todos os outros caminhos usam o formato OpenAI.

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

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

• Leia type e message. code e param estão presentes apenas em alguns erros: trate-os como opcionais. param é sempre null.
• Depois que um stream começou, o status já é 200. Uma falha então chega como um frame de erro dentro do stream.
• Toda resposta de erro traz o header x-request-id.

Tratamento de erros

Faturamento e saldo

• Há um saldo por conta, e o chat e a API o compartilham: primeiro a cota do plano de hoje, depois os créditos comprados. A API não tem uma cota própria.
• Uma requisição reserva o seu orçamento de saída (max_tokens, padrão 4,096) e depois é cobrada pelos tokens que realmente usou, ao preço do modelo.
• Cada resposta informa suas contagens de tokens em usage. A página Chaves e uso mostra o saldo e quanto cada requisição custou.
• Todas as requisições são atendidas igualmente. O único limite de taxa de requisições é a proteção contra flood: 120 requisições por minuto por conta. As requisições enviadas em paralelo esperam em fila.

Limites e saldo Modelos e preços Chaves e uso

Campos que dependem do modelo

Todos os modelos aceitam a mesma requisição. Alguns campos só têm efeito em certos modelos; a tabela indica onde. As páginas dos endpoints listam todos os campos.

Chat Completions

Vindo de um SDK da OpenAI

• Defina a base URL como https://api.shannon-ai.com/v1 e a chave como a sua chave da Shannon. As chamadas de Chat Completions e Responses passam então a funcionar com o SDK como ele é.
• model deve ser um id Shannon. O nome de modelo de outro provedor, como gpt-4o, é respondido com 400 e unknown model.
• O raciocínio vem em um campo próprio: reasoning_content ao lado de content, na mensagem e nos deltas do stream.
• Um stream sempre traz usage no seu último chunk, junto com finish_reason.
• Uma chamada de ferramenta em um stream chega como um único chunk com a string arguments completa.
• Uma resposta tem uma única choice.
• Caminhos da API da OpenAI que não estão na tabela acima, como /v1/embeddings, são respondidos com 404.

Vindo de um SDK da Anthropic

• Defina a base URL como https://api.shannon-ai.com, sem /v1, e a chave como a sua chave da Shannon. O SDK a envia como x-api-key.
• model deve ser um id Shannon.
• max_tokens é opcional nesta API. O padrão é 4,096.
• Uma resposta contém blocos de conteúdo do tipo thinking, text e tool_use. O primeiro bloco nem sempre é o texto: escolha os blocos por type.
• stop_reason é end_turn ou tool_use. Um stream de um modelo Shannon também pode terminar com max_tokens.
• anthropic-version e anthropic-beta são aceitos, para que o SDK funcione sem alterações. Uma requisição não precisa deles.
• Os erros em /v1/messages têm o formato da Anthropic: {"type": "error", "error": {…}}.

As ferramentas de código que falam esses formatos são configuradas da mesma forma: base URL, chave e um id Shannon como modelo. Ferramentas de código em CLI