Visió general

Endpoints

Tots els endpoints són sota una sola URL base i se serveixen per HTTPS.

https://api.shannon-ai.com

Els tres endpoints que produeixen text arriben als mateixos models. Tria el que té el format que el teu codi ja fa servir.

Bases de les sol·licituds

• El cos de cada POST és un sol objecte JSON, de fins a 32 MiB.
• Un camp que l'API no coneix no causa cap error ni té cap efecte. Una sol·licitud escrita per a un altre proveïdor no falla per un camp de més.
• Un camp conegut amb un tipus JSON incorrecte, o un camp obligatori que falta, es respon amb 422. Un cos que no és JSON vàlid es respon amb 400.
• model és un dels ids de Models i preus. Les majúscules i les minúscules no importen.

Una resposta és JSON, o un stream de server-sent events quan la sol·licitud posa stream a true. Cada endpoint respon en el seu propi format. Cada resposta té la capçalera x-request-id.

Què supera una sol·licitud

Una sol·licitud es comprova en un ordre fix abans que s'executi un model. La primera comprovació que falla és la que respon, així que un 401 encara no et diu res del cos.

Forma dels errors

Un error és un objecte JSON amb un error que conté type i message. /v1/messages l'embolcalla de la manera que esperen els SDK d'Anthropic; tots els altres camins fan servir la forma d'OpenAI.

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

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

• Llegeix type i message. code i param només hi són en alguns errors: tracta'ls com a opcionals. param és sempre null.
• Quan un stream ha començat, l'estat ja és 200. Un error llavors arriba com a frame d'error dins del stream.
• Cada resposta d'error porta la capçalera x-request-id.

Gestió d’errors

Facturació i saldo

• Hi ha un saldo per compte, i el xat i l'API el comparteixen: primer la quota del pla d'avui, després el crèdit comprat. L'API no té quota pròpia.
• Una sol·licitud reserva el seu pressupost de sortida (max_tokens, per defecte 4,096) i després es cobra pels tokens que ha fet servir de debò, al preu del model.
• Cada resposta informa dels seus recomptes de tokens a usage. La pàgina Keys & usage mostra el saldo i el que ha costat cada sol·licitud.
• Totes les sol·licituds s'atenen per igual. L'únic límit de freqüència de sol·licituds és la protecció contra inundació: 120 sol·licituds per minut per compte. Les sol·licituds enviades en paral·lel esperen a la cua.

Límits i saldo Models i preus Keys & usage

Camps que depenen del model

Tots els models accepten la mateixa sol·licitud. Uns quants camps només tenen efecte en alguns models; la taula indica en quins. Les pàgines dels endpoints llisten tots els camps.

Chat Completions

Si véns d'un SDK d'OpenAI

• Defineix la URL base com a https://api.shannon-ai.com/v1 i la clau com la teva clau Shannon. Les crides a Chat Completions i Responses funcionen llavors amb l'SDK tal com és.
• model ha de ser un id Shannon. Un nom de model d'un altre proveïdor, com gpt-4o, es respon amb 400 i unknown model.
• El raonament arriba en un camp propi: reasoning_content al costat de content, al missatge i als deltas del stream.
• Un stream porta sempre usage en el seu últim fragment, juntament amb finish_reason.
• Una crida d'eina en un stream arriba com un sol fragment amb la cadena arguments completa.
• Una resposta té una sola opció (choice).
• Els camins de l'API d'OpenAI que no són a la taula de dalt, com /v1/embeddings, es responen amb 404.

Si véns d'un SDK d'Anthropic

• Defineix la URL base com a https://api.shannon-ai.com, sense /v1, i la clau com la teva clau Shannon. L'SDK l'envia com a x-api-key.
• model ha de ser un id Shannon.
• max_tokens és opcional en aquesta API. El valor per defecte és 4,096.
• Una resposta conté blocs de contingut dels tipus thinking, text i tool_use. El primer bloc no sempre és el text: tria els blocs per type.
• stop_reason és end_turn o tool_use. Un stream d'un model Shannon també pot acabar amb max_tokens.
• anthropic-version i anthropic-beta s'accepten, de manera que l'SDK funciona sense canvis. Una sol·licitud no els necessita.
• Els errors a /v1/messages tenen la forma d'Anthropic: {"type": "error", "error": {…}}.

Les eines de programació que parlen aquests formats es configuren igual: URL base, clau i un id Shannon com a model. Eines de programació CLI