Inici ràpid

Fes una primera sol·licitud: obté la teva clau, envia un missatge i llegeix la resposta. L'API parla els formats d'OpenAI i d'Anthropic, així que l'SDK que ja fas servir funciona després de canviar-ne la URL base i la clau.

1. Obté la teva clau

Cada compte té una clau API. Inicia la sessió, obre Keys & usage i copia-la. La clau serveix a tots els endpoints i a tots els models. Keys & usage

2. Apunta el teu client a l'API

Tots els endpoints són sota una sola URL base. Un SDK d'OpenAI la pren amb /v1 al final; un SDK d'Anthropic la pren sense, perquè afegeix /v1/messages per si mateix.

Client	URL base
SDK d'OpenAI i clients compatibles amb OpenAI	`https://api.shannon-ai.com/v1`
SDK d'Anthropic	`https://api.shannon-ai.com`

Tres endpoints produeixen text. Arriben als mateixos models; tria el que té el format que el teu codi ja fa servir.

Endpoint	Format
`POST /v1/chat/completions`	OpenAI Chat Completions
`POST /v1/messages`	Anthropic Messages
`POST /v1/responses`	OpenAI Responses

3. Envia una primera sol·licitud

Envia un missatge user a shannon-3 a l'endpoint Chat Completions. Substitueix YOUR_API_KEY per la teva clau.

POST https://api.shannon-ai.com/v1/chat/completions

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

response = client.chat.completions.create(
    model="shannon-3",
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ],
    max_tokens=1024
)

print(response.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.shannon-ai.com/v1'
});

const response = await client.chat.completions.create({
  model: 'shannon-3',
  messages: [
    { role: 'user', content: 'Hello, Shannon!' }
  ],
  max_tokens: 1024
});

console.log(response.choices[0].message.content);

package main

import (
    "context"
    "fmt"
    openai "github.com/sashabaranov/go-openai"
)

func main() {
    config := openai.DefaultConfig("YOUR_API_KEY")
    config.BaseURL = "https://api.shannon-ai.com/v1"
    client := openai.NewClientWithConfig(config)

    resp, err := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "shannon-3",
            Messages: []openai.ChatCompletionMessage{
                {Role: "user", Content: "Hello, Shannon!"},
            },
            MaxTokens: 1024,
        },
    )
    if err != nil {
        panic(err)
    }
    fmt.Println(resp.Choices[0].Message.Content)
}

curl -X POST "https://api.shannon-ai.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "messages": [
      {"role": "user", "content": "Hello, Shannon!"}
    ],
    "max_tokens": 1024
  }'

Camp	Tipus	Per defecte	Descripció
`model`	`string`		L'id del model que respon. Els ids es llisten a Models i preus.
`messages`	`array`		La conversa fins ara: objectes amb `role` i `content`. L'últim missatge `user` és el prompt. Obligatori.
`max_tokens`	`integer`	`4096`	El pressupost de sortida de la sol·licitud, d'1 a 65,536. La sol·licitud reserva aquesta quantitat del teu saldo i es cobra pel que ha fet servir de debò.
`stream`	`boolean`	`false`	`true` envia la resposta troç a troç mentre s'escriu.

El cos de la sol·licitud és JSON i necessita la capçalera Content-Type: application/json. La llista completa de camps és a la pàgina de l'endpoint. Chat Completions

La resposta

Una crida sense stream retorna un sol objecte JSON quan la resposta és completa. Els textos i els nombres de sota són exemples.

200 JSON

{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! What would you like to work on?",
        "reasoning_content": "A greeting. A short, friendly reply fits."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1386,
    "completion_tokens": 74,
    "total_tokens": 1460
  }
}

Camp	Tipus	Descripció
`id`	`string`	`chatcmpl-` seguit de 32 caràcters hexadecimals.
`object`	`string`	Sempre `chat.completion`.
`created`	`integer`	L'hora de la resposta en segons Unix.
`model`	`string`	L'id publicat del model que ha respost, també quan has enviat un àlies o una altra grafia.
`choices`	`array`	Sempre una sola entrada, amb `index` 0.
`choices[0].message.role`	`string`	Sempre `assistant`.
`choices[0].message.content`	`string \| null`	La resposta. Pot ser `null` quan la resposta porta `tool_calls`.
`choices[0].message.reasoning_content`	`string \| null`	El raonament del model abans de la seva resposta, o `null` quan no n'hi ha.
`choices[0].message.tool_calls`	`array`	Només hi és quan el model crida una de les eines que has declarat.
`choices[0].finish_reason`	`string`	`stop` per a una resposta, `tool_calls` quan el model crida una eina.
`usage.prompt_tokens`	`integer`	Els tokens que el model ha llegit per a aquesta resposta. A `shannon-2-*` i a la família Shannon 3 pot ser més que el text que has enviat.
`usage.completion_tokens`	`integer`	Els tokens que ha escrit el model.
`usage.total_tokens`	`integer`	El total. El cobrament d'un model Shannon es calcula a partir d'aquest nombre.

usage conté recomptes de tokens, no diners. Allò que la crida ha descomptat del teu saldo es mostra per sol·licitud a Keys & usage; com es calcula és a Límits i saldo. Límits i saldo
Cada resposta, també un error i un stream, té la capçalera x-request-id. Si la teva sol·licitud porta una capçalera x-request-id, el seu valor torna; si no, el valor són 12 caràcters hexadecimals. Guarda'l als teus logs: identifica aquesta sol·licitud concreta.

La mateixa crida com a stream

Posa stream a true per llegir la resposta mentre s'escriu. Tota la resta de la sol·licitud continua igual.

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1"
)

stream = client.chat.completions.create(
    model="shannon-3",
    messages=[
        {"role": "user", "content": "Hello, Shannon!"}
    ],
    max_tokens=1024,
    stream=True
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.shannon-ai.com/v1'
});

const stream = await client.chat.completions.create({
  model: 'shannon-3',
  messages: [
    { role: 'user', content: 'Hello, Shannon!' }
  ],
  max_tokens: 1024,
  stream: true
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}

curl -N -X POST "https://api.shannon-ai.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "messages": [
      {"role": "user", "content": "Hello, Shannon!"}
    ],
    "max_tokens": 1024,
    "stream": true
  }'

Cada frame del stream és una línia que comença per data: i conté un objecte JSON. Un frame, imprès en diverses línies:

Un frame

{
  "id": "chatcmpl-9b2f6c1e4a7d4f0f8a3c5d2e1b6a7c90",
  "object": "chat.completion.chunk",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "Hello! "
      },
      "finish_reason": null
    }
  ]
}

Frames, per ordre	delta	finish_reason
Mentre el model raona. Zero o més frames.	`{"reasoning_content": "…"}`	`null`
La resposta, troç a troç. Zero o més frames.	`{"content": "…"}`	`null`
L'últim frame JSON. També porta `usage`; no cal que el demanis.	`{}`	`"stop"`
El final del stream: la línia `data: [DONE]`.

La resposta té l'estat 200 i content-type: text/event-stream. Cada frame és una línia data: <json> seguida d'una línia buida.
Cada 15 segons arriba una línia : ping. És un comentari que manté la connexió oberta; els clients SSE l'ignoren.
Un error després que el stream s'hagi obert arriba com un frame data: {"error": {…}}. L'estat continua sent 200, així que comprova els frames.

Streaming

Si la crida falla

Un error és un objecte JSON amb un error que conté type i message. Aquestes són les respostes que més troba una primera crida.

Estat	Tipus	Missatge	Què vol dir
`401`	`authentication_error`	`Missing authentication`	Cap clau no ha arribat a l'API. Envia `Authorization: Bearer` seguit de la teva clau.
`401`	`authentication_error`	`Invalid API key`	La clau no és la clau actual d'un compte. Torna-la a copiar de Keys & usage.
`400`	`invalid_request_error`	`unknown model: <id>`	`model` no és un id publicat. Fes servir un id de Models i preus.
`422`	`invalid_request_error`	`Failed to deserialize the JSON body into the target type…`	Un camp té un tipus JSON incorrecte, o falta `messages`.
`429`	`rate_limit_error`	`Quota exceeded. Upgrade your plan at shannon-ai.com/plan`	El pressupost de sortida de la sol·licitud no cap al teu saldo.

Gestió d’errors

On anar després

Models i preus — Tria un model: ids, finestres de context i preus.
Chat Completions — Tots els camps de sol·licitud, camps de resposta i esdeveniments de stream de l'endpoint que has cridat.
Streaming — Els frames d'un stream, les línies keep-alive i els errors dins d'un stream.
Crida de funcions — Deixa que el model cridi les teves funcions.
Límits i saldo — Què reserva i què costa una sol·licitud, i quantes sol·licituds pots enviar.
Playground de l’API — Prova sol·licituds al navegador amb la teva clau.