API Responses

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

A solicitude máis pequena é un id de modelo e un texto. A resposta non ten stream a menos que o 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."
  }'

A resposta é un obxecto de resposta. O seu output contén o razoamento, cando o modelo razoou, e a mensaxe:

{
  "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 da solicitude

model e input son o que necesita unha solicitude. A columna Aplicado por indica os modelos nos que un campo cambia a resposta. Os modelos open-weight alojados son os doce ids da lista de modelos; a familia Shannon 3 é shannon-3, shannon-3-pro, shannon-3.1 e shannon-3.1-pro. Modelos e prezos

Acéptanse previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user e prompt_cache_key para que o código de cliente existente funcione sen cambios. Non alteran a resposta. Como non se garda ningunha conversa, unha solicitude posterior leva os turnos anteriores en input.

Elementos de entrada

Un elemento de entrada é ou ben unha mensaxe, cun role e un content, ou ben un elemento tipado que leva unha chamada a unha ferramenta ou o seu resultado. content é unha cadea ou unha matriz de partes.

Pon as instrucións no campo instructions. Cun id da familia Shannon 3, pon na mensaxe user as instrucións que deban cumprirse.

Os elementos do output dunha resposta poden volver a input tal cales: os elementos message e function_call lense e os elementos reasoning omítense.

Partes de contido

Nos niveis Shannon, as imaxes e os ficheiros lense do último elemento user de input. Os tamaños e os límites teñen a súa propia páxina. Imaxes e ficheiros

Unha solicitude con instrucións e opcións

Esta solicitude envía instrucións, unha conversa como elementos de entrada, un límite de saída, unha temperatura e un esforzo de razoamento. Usa un modelo open-weight alojado, que aplica todos eles.

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

A resposta dun modelo open-weight alojado ten id, object, model, created_at, status, output e usage. O seu usage engade os tokens lidos da caché e os tokens gastados en razoamento:

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

O obxecto de resposta

id, object, status, output e usage están en todas as respostas. Constrúe o teu código sobre eles.

Elementos de saída

Os SDK de OpenAI únenche o texto da mensaxe en response.output_text.

Streaming

Define stream como true para obter server-sent events. Cada frame ten unha liña event: co nome do evento e unha liña data: cun obxecto JSON; o obxecto repite o nome en type. Asocia os deltas co seu elemento por output_index.

Co SDK de OpenAI, le os eventos polo 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
  }'

Os eventos chegan nesta orde. Os grupos de razoamento, mensaxe e chamadas a ferramentas aparecen só cando a resposta os ten.

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

Nos niveis Shannon, unha resposta fallida remata con response.failed en vez de response.completed. O seu response.status é failed e response.error contén un code, rate_limit_exceeded ou server_error, e un message.

Nos modelos open-weight alojados, un fallo é un evento error con code api_error e un message. Despois segue chegando response.completed.

Considera un stream como fallido cando contén un evento response.failed ou error, e envía a solicitude de novo.

Ferramentas

Unha ferramenta é unha función que executa o teu código. Descríbea en tools; cando o modelo a quere, a resposta contén un elemento function_call no lugar da mensaxe, ou xunto a ela.

Unha definición de ferramenta en tools:

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

O output dunha resposta que a chama:

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

Executa a función e envía a solicitude de novo coa chamada e o seu resultado engadidos 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\"}"
  }
]

Só se len as ferramentas de tipo function. En shannon-1.6-*, shannon-2-* e shannon-coder-1, o esquema de parameters redúcese ás palabras clave comúns de JSON Schema: oneOf lese como anyOf, e palabras clave como $ref, additionalProperties, const, default e title non se pasan ao modelo.

Os valores required e unha función nomeada de tool_choice aplícanos os modelos open-weight alojados.

O bucle de ferramentas descríbese por completo na súa propia páxina. Chamadas a funcións

Saída estruturada

Este formato escribe a saída estruturada como text.format. O esquema está directamente en format, xunto a name e strict, non baixo un membro json_schema como en Chat Completions.

• {"type": "json_object"} pide calquera obxecto JSON.
• {"type": "json_schema", "name", "schema", "strict"} pide JSON que siga o teu esquema. strict é true cando o 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"
        ]
      }
    }
  }
}

O JSON chega como texto na parte output_text da mensaxe; analízao ti mesmo. Un modelo open-weight alojado sen saída estruturada devolve 400.

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

Que modelo acepta cada forma está listado na súa propia páxina. Saídas estruturadas

Razoamento

Un modelo que razoa devolve o seu razoamento como un elemento de saída de tipo reasoning, antes da mensaxe. Nun stream chega como eventos response.reasoning_summary_text.delta.

Os modelos open-weight alojados aplican reasoning.effort: off, low, medium ou high, con high cando non envías nada. off non devolve ningún elemento de razoamento. Envíao como obxecto; unha cadea simple non se le neste endpoint.

Os esforzos descríbense na súa propia páxina. Esforzo de razoamento

Límite de saída

max_output_tokens é 4,096 cando non o envías. É o número de tokens que se reservan do teu saldo cando comeza a solicitude; cando a resposta está completa, esa cantidade substitúese polo que usou a solicitude. Un valor que non cabe no saldo que che queda devolve 429 Quota exceeded.

Limita a lonxitude da resposta en shannon-1.6-*, shannon-2-* e shannon-coder-1, e a lonxitude do texto da resposta nos modelos open-weight alojados.

Neste endpoint shannon-coder-1 cóbrase en tokens do teu saldo, como todos os demais modelos.

O corpo dunha solicitude pode ser de ata 32 MiB. Límites e saldo

Erros

Os erros usan o corpo de erro de OpenAI: un obxecto error con type e message; algúns levan tamén code e param co valor null. A táboa mostra o que este endpoint devolve con máis frecuencia. A lista completa, con indicacións sobre que reintentar, ten a súa propia páxina. Xestión de erros