API Responses

POST https://api.shannon-ai.com/v1/responses

La sol·licitud més petita és un id de model i un text. La resposta no va en streaming tret que ho demanis.

from openai import OpenAI

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

response = client.responses.create(
    model="shannon-3",
    input="Say hello in one sentence.",
)

print(response.output_text)

import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "shannon-3",
  input: "Say hello in one sentence.",
});

console.log(response.output_text);

curl https://api.shannon-ai.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "input": "Say hello in one sentence."
  }'

La resposta és un objecte de resposta. El seu output conté el raonament, quan el model ha raonat, i el missatge:

{
  "id": "resp_5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
  "object": "response",
  "created_at": 1791625200,
  "model": "shannon-3",
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "metadata": {},
  "parallel_tool_calls": true,
  "temperature": null,
  "tool_choice": "auto",
  "tools": [],
  "top_p": null,
  "output": [
    {
      "id": "rs_8a2e6c1f4b7d4e03b9c5a1d70f3e2b64",
      "type": "reasoning",
      "summary": [
        {
          "type": "summary_text",
          "text": "The user wants a greeting in one sentence. Keep it short and friendly."
        }
      ]
    },
    {
      "id": "msg_1c7b9e3a5d2f4a86b0e4c8d19a6f7e25",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello, it is good to meet you.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 1184,
    "output_tokens": 46,
    "total_tokens": 1230
  }
}

Camps de la sol·licitud

model i input són el que necessita una sol·licitud. La columna L'apliquen indica els models en què un camp canvia la resposta. Els models open-weight hostejats són els dotze ids de la llista de models; la família Shannon 3 és shannon-3, shannon-3-pro, shannon-3.1 i shannon-3.1-pro. Models i preus

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user i prompt_cache_key s'accepten perquè el codi client existent funcioni sense canvis. No canvien la resposta. Com que no es desa cap conversa, una sol·licitud de seguiment porta els torns anteriors a input.

Elements d'entrada

Un element d'entrada és un missatge, amb un role i un content, o un element tipat que porta una crida d'eina o el seu resultat. content és una cadena o una matriu de parts.

Posa les instruccions al camp instructions. Amb un id de la família Shannon 3, posa les instruccions que s'han de complir al missatge user.

Els elements d'output d'una resposta poden tornar a input tal com són: els elements message i function_call es llegeixen, els elements reasoning s'ometen.

Parts de contingut

Als nivells Shannon, les imatges i els fitxers es llegeixen de l'últim element user d'input. Les mides i els límits tenen la seva pròpia pàgina. Imatges i fitxers

Una sol·licitud amb instruccions i opcions

Aquesta sol·licitud envia instruccions, una conversa com a elements d'entrada, un límit de sortida, una temperatura i un esforç de raonament. Fa servir un model open-weight hostejat, que els aplica tots.

from openai import OpenAI

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

response = client.responses.create(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    instructions="You are a physics teacher. Answer in two sentences.",
    input=[
        {"role": "user", "content": "Why is the sky blue?"},
        {"role": "assistant", "content": "Air scatters blue light more than red light."},
        {"role": "user", "content": "And why are sunsets red?"},
    ],
    max_output_tokens=512,
    temperature=0.3,
    reasoning={"effort": "low"},
)

for item in response.output:
    if item.type == "reasoning":
        print("reasoning:", item.summary[0].text)
    elif item.type == "message":
        print("answer:", item.content[0].text)
print(response.usage)

import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
  instructions: "You are a physics teacher. Answer in two sentences.",
  input: [
    { role: "user", content: "Why is the sky blue?" },
    { role: "assistant", content: "Air scatters blue light more than red light." },
    { role: "user", content: "And why are sunsets red?" },
  ],
  max_output_tokens: 512,
  temperature: 0.3,
  reasoning: { effort: "low" },
});

for (const item of response.output) {
  if (item.type === "reasoning") console.log("reasoning:", item.summary[0].text);
  if (item.type === "message") console.log("answer:", item.content[0].text);
}
console.log(response.usage);

curl https://api.shannon-ai.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    "instructions": "You are a physics teacher. Answer in two sentences.",
    "input": [
      {"role": "user", "content": "Why is the sky blue?"},
      {"role": "assistant", "content": "Air scatters blue light more than red light."},
      {"role": "user", "content": "And why are sunsets red?"}
    ],
    "max_output_tokens": 512,
    "temperature": 0.3,
    "reasoning": {"effort": "low"}
  }'

La resposta d'un model open-weight hostejat té id, object, model, created_at, status, output i usage. El seu usage afegeix els tokens llegits de la cache i els tokens gastats en raonament:

{
  "usage": {
    "input_tokens": 58,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 67,
    "output_tokens_details": {
      "reasoning_tokens": 19
    },
    "total_tokens": 125
  }
}

L'objecte de resposta

id, object, status, output i usage són a totes les respostes. Construeix el teu codi sobre aquests.

Elements de sortida

Els SDK d'OpenAI uneixen per tu el text del missatge a response.output_text.

Streaming

Posa stream a true per obtenir server-sent events. Cada frame té una línia event: amb el nom de l'esdeveniment i una línia data: amb un objecte JSON; l'objecte repeteix el nom a type. Associa els deltas al seu element per output_index.

Amb l'SDK d'OpenAI, llegeix els esdeveniments pel seu type:

from openai import OpenAI

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

stream = client.responses.create(
    model="shannon-3",
    input="Explain server-sent events in three sentences.",
    stream=True,
)

for event in stream:
    kind = getattr(event, "type", "error")     # an event without a type is an error event
    if kind == "response.reasoning_summary_text.delta":
        pass                                   # a piece of reasoning: event.delta
    elif kind == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif kind == "response.output_item.done" and event.item.type == "function_call":
        print("\ntool call:", event.item.name, event.item.arguments)
    elif kind == "response.completed":
        print("\n", event.response.usage)
    elif kind in ("response.failed", "error"):
        raise RuntimeError("the stream failed, send the request again")

import OpenAI from "openai";

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

const stream = await client.responses.create({
  model: "shannon-3",
  input: "Explain server-sent events in three sentences.",
  stream: true,
});

for await (const event of stream) {
  if (event.type === "response.reasoning_summary_text.delta") {
    // a piece of reasoning: event.delta
  } else if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  } else if (event.type === "response.output_item.done" && event.item.type === "function_call") {
    console.log("\ntool call:", event.item.name, event.item.arguments);
  } else if (event.type === "response.completed") {
    console.log("\n", event.response.usage);
  } else if (event.type === "response.failed" || event.type === "error") {
    throw new Error("the stream failed, send the request again");
  }
}

curl -N https://api.shannon-ai.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "input": "Explain server-sent events in three sentences.",
    "stream": true
  }'

Els esdeveniments arriben en aquest ordre. Els grups del raonament, del missatge i de les crides d'eina només hi són quan la resposta els té.

event: response.created
data: {"type":"response.created","response":{"id":"resp_5f0c…","object":"response","status":"in_progress","output":[], …}}

event: response.in_progress
data: {"type":"response.in_progress","response":{"id":"resp_5f0c…","object":"response","status":"in_progress","output":[], …}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_1c7b…","type":"message","role":"assistant","status":"in_progress","content":[]}}

event: response.content_part.added
data: {"type":"response.content_part.added","output_index":0,"content_index":0,"part":{"type":"output_text","text":""}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"Server-sent"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":" events let a server push text over one HTTP reply."}

event: response.output_text.done
data: {"type":"response.output_text.done","output_index":0,"content_index":0,"text":"Server-sent events let a server push text over one HTTP reply."}

event: response.content_part.done
data: {"type":"response.content_part.done","output_index":0,"content_index":0,"part":{"type":"output_text","text":"Server-sent events let a server push text over one HTTP reply."}}

event: response.output_item.done
data: {"type":"response.output_item.done","output_index":0,"item":{"id":"msg_1c7b…","type":"message","role":"assistant","status":"completed","content":[{"type":"output_text","text":"Server-sent events let a server push text over one HTTP reply.","annotations":[]}]}}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_5f0c…","object":"response","status":"completed","output":[…],"usage":{"input_tokens":1190,"output_tokens":18,"total_tokens":1208}, …}}

Un stream que falla

Als nivells Shannon, una resposta fallida acaba amb response.failed en lloc de response.completed. El seu response.status és failed i response.error conté un code, rate_limit_exceeded o server_error, i un message.

En els models open-weight hostejats, un error és un esdeveniment error amb code api_error i un message. response.completed el segueix igualment.

Tracta un stream com a fallit quan conté un esdeveniment response.failed o error, i torna a enviar la sol·licitud.

Eines

Una eina és una funció que executa el teu codi. Descriu-la a tools; quan el model la vol, la resposta conté un element function_call en lloc del missatge, o al costat.

Una definició d'eina a tools:

[
  {
    "type": "function",
    "name": "get_weather",
    "description": "Current weather for a city.",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string"
        }
      },
      "required": [
        "city"
      ]
    }
  }
]

L'output d'una resposta que la crida:

[
  {
    "id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "type": "function_call",
    "name": "get_weather",
    "call_id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "arguments": "{\"city\":\"Paris\"}"
  }
]

Executa la funció i torna a enviar la sol·licitud amb la crida i el seu resultat afegits a input:

[
  {
    "role": "user",
    "content": "What is the weather in Paris?"
  },
  {
    "type": "function_call",
    "call_id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "name": "get_weather",
    "arguments": "{\"city\":\"Paris\"}"
  },
  {
    "type": "function_call_output",
    "call_id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
    "output": "{\"temperature_c\": 18, \"sky\": \"cloudy\"}"
  }
]

Només es llegeixen les eines del tipus function. A shannon-1.6-*, shannon-2-* i shannon-coder-1, l'esquema de parameters es redueix a les paraules clau comunes de JSON Schema: oneOf es llegeix com a anyOf, i paraules clau com $ref, additionalProperties, const, default i title no es passen al model.

Els valors required i una funció amb nom de tool_choice els apliquen els models open-weight hostejats.

El bucle d'eines es descriu sencer a la seva pròpia pàgina. Crida de funcions

Sortida estructurada

Aquest format escriu la sortida estructurada com a text.format. L'esquema és directament a format, al costat de name i strict, no sota un membre json_schema com a Chat Completions.

• {"type": "json_object"} demana qualsevol objecte JSON.
• {"type": "json_schema", "name", "schema", "strict"} demana JSON que segueixi el teu esquema. strict és true quan l'omets.

{
  "model": "shannon-1.6-lite",
  "input": "Extract the city and the date: 'The conference opens in Lisbon on 12 May 2027.'",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "event",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "description": "ISO 8601 date"
          }
        },
        "required": [
          "city",
          "date"
        ]
      }
    }
  }
}

El JSON arriba com a text a la part output_text del missatge; analitza'l tu mateix. Un model open-weight hostejat sense sortida estructurada retorna 400.

{"city": "Lisbon", "date": "2027-05-12"}

Quin model accepta quina forma es llista a la seva pròpia pàgina. Sortides estructurades

Raonament

Un model que raona retorna el seu raonament com un element de sortida del tipus reasoning, abans del missatge. En un stream arriba com a esdeveniments response.reasoning_summary_text.delta.

Els models open-weight hostejats apliquen reasoning.effort: off, low, medium o high, amb high quan no envies res. off no retorna cap element de raonament. Envia'l com a objecte; una cadena sola no es llegeix en aquest endpoint.

Els esforços es descriuen a la seva pròpia pàgina. Esforç de raonament

Límit de sortida

max_output_tokens és 4,096 quan no l'envies. És el nombre de tokens que es reserva del teu saldo quan comença la sol·licitud; quan la resposta és completa, aquesta quantitat se substitueix pel que ha fet servir la sol·licitud. Un valor que no cap al saldo que et queda retorna 429 Quota exceeded.

Limita la longitud de la resposta a shannon-1.6-*, shannon-2-* i shannon-coder-1, i la longitud del text de la resposta en els models open-weight hostejats.

En aquest endpoint, shannon-coder-1 es cobra en tokens del teu saldo, com tots els altres models.

El cos d'una sol·licitud pot ser de fins a 32 MiB. Límits i saldo

Errors

Els errors fan servir el cos d'error d'OpenAI: un objecte error amb type i message; alguns porten també code i param amb el valor null. La taula llista el que aquest endpoint retorna més sovint. La llista completa, amb què cal reintentar, té la seva pròpia pàgina. Gestió d’errors