API Responses

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

La solicitud más pequeña es un id de modelo y un texto. La respuesta no va con stream a menos que lo pidas.

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 respuesta es un objeto de respuesta. Su output contiene el razonamiento, cuando el modelo razonó, y el mensaje:

{
  "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
  }
}

Campos de solicitud

model e input son lo que necesita una solicitud. La columna Lo aplican nombra los modelos en los que un campo cambia la respuesta. Los modelos de pesos abiertos alojados son los doce ids de la lista de modelos; la familia Shannon 3 es shannon-3, shannon-3-pro, shannon-3.1 y shannon-3.1-pro. Modelos y precios

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user y prompt_cache_key se aceptan para que el código de cliente existente funcione sin cambios. No modifican la respuesta. Como no se guarda ninguna conversación, una solicitud posterior lleva los turnos anteriores en input.

Elementos de entrada

Un elemento de entrada es un mensaje, con un role y un content, o un elemento tipado que lleva una llamada a herramienta o su resultado. content es una cadena o un array de partes.

Pon las instrucciones en el campo instructions. Con un id de la familia Shannon 3, pon las instrucciones que deben cumplirse en el mensaje user.

Los elementos del output de una respuesta pueden volver a input tal cual: los elementos message y function_call se leen, los elementos reasoning se omiten.

Partes de contenido

En los niveles Shannon las imágenes y los archivos se leen del último elemento user de input. Los tamaños y límites tienen su propia página. Imágenes y archivos

Una solicitud con instrucciones y opciones

Esta solicitud envía instrucciones, una conversación como elementos de entrada, un límite de salida, una temperatura y un esfuerzo de razonamiento. Usa un modelo de pesos abiertos alojado, que aplica todos ellos.

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 respuesta de un modelo de pesos abiertos alojado tiene id, object, model, created_at, status, output y usage. Su usage añade los tokens leídos de la caché y los tokens gastados en razonamiento:

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

El objeto de respuesta

id, object, status, output y usage están en toda respuesta. Basa tu código en ellos.

Elementos de salida

Los SDK de OpenAI unen por ti el texto del mensaje en response.output_text.

Streaming

Establece stream en true para recibir server-sent events. Cada trama tiene una línea event: con el nombre del evento y una línea data: con un objeto JSON; el objeto repite el nombre en type. Asocia los deltas con su elemento mediante output_index.

Con el SDK de OpenAI, lee los eventos por su 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
  }'

Los eventos llegan en este orden. Los grupos de razonamiento, mensaje y llamadas a herramientas aparecen solo cuando la respuesta los tiene.

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

En los niveles Shannon una respuesta fallida termina con response.failed en lugar de response.completed. Su response.status es failed y response.error contiene un code, rate_limit_exceeded o server_error, y un message.

En los modelos de pesos abiertos alojados un fallo es un evento error con code api_error y un message. response.completed lo sigue de todos modos.

Considera fallido un stream cuando contiene un evento response.failed o error, y envía la solicitud de nuevo.

Herramientas

Una herramienta es una función que ejecuta tu código. Descríbela en tools; cuando el modelo la quiere, la respuesta contiene un elemento function_call en lugar del mensaje o junto a él.

Una definición de herramienta en tools:

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

El output de una respuesta que la llama:

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

Ejecuta la función y envía la solicitud de nuevo con la llamada y su resultado añadidos 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\"}"
  }
]

Solo se leen las herramientas de tipo function. En shannon-1.6-*, shannon-2-* y shannon-coder-1 el esquema de parameters se reduce a las palabras clave comunes de JSON Schema: oneOf se lee como anyOf, y palabras clave como $ref, additionalProperties, const, default y title no se pasan al modelo.

Los valores de tool_choice required y una función con nombre los aplican los modelos de pesos abiertos alojados.

El bucle de herramientas se describe por completo en su propia página. Llamadas a funciones

Salida estructurada

Este formato escribe la salida estructurada como text.format. El esquema va directamente en format, junto a name y strict, no bajo un miembro json_schema como en Chat Completions.

• {"type": "json_object"} pide cualquier objeto JSON.
• {"type": "json_schema", "name", "schema", "strict"} pide JSON que siga tu esquema. strict es true cuando lo omites.

{
  "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 llega como texto en la parte output_text del mensaje; analízalo tú mismo. Un modelo de pesos abiertos alojado sin salida estructurada devuelve 400.

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

Qué modelo acepta cada forma se enumera en su propia página. Salidas estructuradas

Razonamiento

Un modelo que razona devuelve su razonamiento como un elemento de salida de tipo reasoning, antes del mensaje. En un stream llega como eventos response.reasoning_summary_text.delta.

Los modelos de pesos abiertos alojados aplican reasoning.effort: off, low, medium o high, con high cuando no envías nada. off no devuelve ningún elemento de razonamiento. Envíalo como objeto; una cadena simple no se lee en este endpoint.

Los esfuerzos se describen en su propia página. Esfuerzo de razonamiento

Límite de salida

max_output_tokens es 4,096 cuando no lo envías. Es la cantidad de tokens que se reserva de tu saldo al empezar la solicitud; cuando la respuesta está completa, esa cantidad se sustituye por lo que usó la solicitud. Un valor que no cabe en tu saldo restante devuelve 429 Quota exceeded.

Limita la longitud de la respuesta en shannon-1.6-*, shannon-2-* y shannon-coder-1, y la longitud del texto de la respuesta en los modelos de pesos abiertos alojados.

En este endpoint shannon-coder-1 se cobra en tokens de tu saldo, como cualquier otro modelo.

El cuerpo de una solicitud puede tener hasta 32 MiB. Límites y saldo

Errores

Los errores usan el cuerpo de error de OpenAI: un objeto error con type y message; algunos llevan también code y param con el valor null. La tabla enumera lo que este endpoint devuelve con más frecuencia. La lista completa, con qué reintentar, tiene su propia página. Manejo de errores