Visión xeral

Endpoints

Todos os endpoints están baixo unha URL base e serven por HTTPS.

https://api.shannon-ai.com

Os tres endpoints que producen texto chegan aos mesmos modelos. Escolle aquel cuxo formato xa usa o teu código.

Conceptos básicos da solicitude

• O corpo de cada POST é un obxecto JSON, de ata 32 MiB.
• Un campo que a API non coñece non causa ningún erro nin ten efecto. Unha solicitude escrita para outro provedor non falla por un campo adicional.
• Un campo coñecido co tipo JSON incorrecto, ou un campo obrigatorio ausente, recibe 422. Un corpo que non é JSON válido recibe 400.
• model é un dos ids de Modelos e prezos. Non importan as maiúsculas e minúsculas.

Unha resposta é JSON, ou un stream de server-sent events cando a solicitude define stream como true. Cada endpoint responde no seu propio formato. Todas as respostas teñen a cabeceira x-request-id.

O que pasa unha solicitude

Unha solicitude comprobase nunha orde fixa antes de que se execute un modelo. Responde a primeira comprobación que falla, así que un 401 aínda non che di nada sobre o corpo.

Forma dos erros

Un erro é un obxecto JSON cun error que contén type e message. /v1/messages envólveo como esperan os SDK de Anthropic; todas as demais rutas usan a forma de OpenAI.

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

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

• Le type e message. code e param só están presentes nalgúns erros: trátaos como opcionais. param é sempre null.
• Despois de que comece un stream, o estado xa é 200. Un fallo chega entón como un frame de erro dentro do stream.
• Todas as respostas de erro levan a cabeceira x-request-id.

Xestión de erros

Facturación e saldo

• Hai un saldo por conta, e o chat e a API compártenno: primeiro a cota do plan de hoxe e despois o crédito adquirido. A API non ten cota propia.
• Unha solicitude reserva o seu orzamento de saída (max_tokens, 4,096 por defecto) e despois cóbrase polos tokens que realmente usou, ao prezo do modelo.
• Todas as respostas informan dos seus recontos de tokens en usage. A páxina Claves e uso mostra o saldo e o que custou cada solicitude.
• Todas as solicitudes se atenden por igual. O único límite á taxa de solicitudes é a protección contra inundación: 120 solicitudes por minuto e conta. As solicitudes enviadas en paralelo agardan na cola.

Límites e saldo Modelos e prezos Claves e uso

Campos que dependen do modelo

Todos os modelos aceptan a mesma solicitude. Uns poucos campos teñen efecto só nalgúns modelos; a táboa indica onde. As páxinas dos endpoints listan todos os campos.

Chat Completions

Se vés dun SDK de OpenAI

• Define a URL base como https://api.shannon-ai.com/v1 e a clave como a túa clave de Shannon. As chamadas a Chat Completions e Responses funcionan entón co SDK tal como está.
• model debe ser un id de Shannon. Un nome de modelo doutro provedor, como gpt-4o, recibe 400 e unknown model.
• O razoamento vén nun campo propio: reasoning_content xunto a content, na mensaxe e nos deltas do stream.
• Un stream leva sempre usage no seu último chunk, xunto con finish_reason.
• Unha chamada a unha ferramenta nun stream chega como un chunk coa cadea arguments completa.
• Unha resposta ten unha soa opción (choice).
• As rutas da API de OpenAI que non están na táboa anterior, como /v1/embeddings, reciben 404.

Se vés dun SDK de Anthropic

• Define a URL base como https://api.shannon-ai.com, sen /v1, e a clave como a túa clave de Shannon. O SDK envíaa como x-api-key.
• model debe ser un id de Shannon.
• max_tokens é opcional nesta API. O seu valor predeterminado é 4,096.
• Unha resposta contén bloques de contido de tipo thinking, text e tool_use. O primeiro bloque non sempre é o texto: escolle os bloques por type.
• stop_reason é end_turn ou tool_use. Un stream dun modelo Shannon tamén pode rematar con max_tokens.
• Acéptanse anthropic-version e anthropic-beta, así que o SDK funciona sen cambios. Unha solicitude non os necesita.
• Os erros en /v1/messages teñen a forma de Anthropic: {"type": "error", "error": {…}}.

As ferramentas de programación que falan estes formatos configúranse da mesma maneira: URL base, clave e un id de Shannon como modelo. Ferramentas de código CLI