API Responses

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

A menor requisição é um id de modelo e um texto. A resposta não vem em stream, a menos que você peça.

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 é um objeto de resposta. O seu output contém o raciocínio, quando o modelo raciocinou, e a mensagem:

{
  "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 requisição

model e input são o que uma requisição precisa. A coluna Aplicado por nomeia os modelos nos quais um campo muda a resposta. Os modelos open-weight hospedados são os doze ids da lista de modelos; a família Shannon 3 é shannon-3, shannon-3-pro, shannon-3.1 e shannon-3.1-pro. Modelos e preços

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user e prompt_cache_key são aceitos para que o código de clientes existentes funcione sem alterações. Eles não mudam a resposta. Como nenhuma conversa é armazenada, uma requisição seguinte leva os turnos anteriores em input.

Itens de entrada

Um item de entrada é uma mensagem, com role e content, ou um item tipado que traz uma chamada de ferramenta ou o seu resultado. content é uma string ou um array de partes.

Coloque as instruções no campo instructions. Com um id da família Shannon 3, coloque as instruções que precisam valer na mensagem user.

Os itens de output de uma resposta podem voltar para input como estão: os itens message e function_call são lidos, os itens reasoning são ignorados.

Partes de conteúdo

Nos níveis Shannon, imagens e arquivos são lidos do último item user de input. Tamanhos e limites têm a sua própria página. Imagens e arquivos

Uma requisição com instruções e opções

Esta requisição envia instruções, uma conversa como itens de entrada, um limite de saída, uma temperatura e um esforço de raciocínio. Ela usa um modelo open-weight hospedado, 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 de um modelo open-weight hospedado tem id, object, model, created_at, status, output e usage. O seu usage acrescenta os tokens lidos do cache e os tokens gastos com raciocínio:

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

O objeto de resposta

id, object, status, output e usage estão em toda resposta. Baseie o seu código nesses campos.

Itens de saída

Os SDKs da OpenAI juntam para você o texto da mensagem em response.output_text.

Streaming

Defina stream como true para receber server-sent events. Cada frame tem uma linha event: com o nome do evento e uma linha data: com um objeto JSON; o objeto repete o nome em type. Associe os deltas ao seu item por output_index.

Com o SDK da OpenAI, leia os eventos pelo 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 chegam nesta ordem. Os grupos de raciocínio, mensagem e chamadas de ferramenta aparecem apenas quando a resposta os tem.

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}, …}}

Um stream que falha

Nos níveis Shannon, uma resposta com falha termina com response.failed no lugar de response.completed. O seu response.status é failed e response.error contém um code, rate_limit_exceeded ou server_error, e uma message.

Nos modelos open-weight hospedados, uma falha é um evento error com code api_error e uma message. response.completed ainda vem depois dele.

Trate um stream como falho quando ele contiver um evento response.failed ou error, e envie a requisição novamente.

Ferramentas

Uma ferramenta é uma função que o seu código executa. Descreva-a em tools; quando o modelo a quer, a resposta contém um item function_call no lugar da mensagem ou ao lado dela.

Uma definição de ferramenta em tools:

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

O output de uma resposta que a chama:

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

Execute a função e envie a requisição de novo, com a chamada e o seu resultado acrescentados 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\"}"
  }
]

Apenas ferramentas do tipo function são lidas. Em shannon-1.6-*, shannon-2-* e shannon-coder-1, o schema de parameters é reduzido às palavras-chave comuns do JSON Schema: oneOf é lido como anyOf, e palavras-chave como $ref, additionalProperties, const, default e title não são repassadas ao modelo.

Os valores required e uma função nomeada de tool_choice são aplicados pelos modelos open-weight hospedados.

O ciclo de ferramentas é descrito por completo na sua própria página. Chamada de funções

Saída estruturada

Este formato escreve a saída estruturada como text.format. O schema fica diretamente em format, ao lado de name e strict, e não sob um membro json_schema como no Chat Completions.

• {"type": "json_object"} pede qualquer objeto JSON.
• {"type": "json_schema", "name", "schema", "strict"} pede um JSON que siga o seu schema. strict é true quando você o omite.

{
  "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 mensagem; faça o parse você mesmo. Um modelo open-weight hospedado sem saída estruturada retorna 400.

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

Qual modelo aceita qual forma está listado na sua própria página. Saídas estruturadas

Raciocínio

Um modelo que raciocina retorna o seu raciocínio como um item de saída do tipo reasoning, antes da mensagem. Em um stream, ele chega como eventos response.reasoning_summary_text.delta.

Os modelos open-weight hospedados aplicam reasoning.effort: off, low, medium ou high, com high quando você não envia nada. off não retorna item de raciocínio. Envie-o como objeto; uma string simples não é lida neste endpoint.

Os níveis de esforço são descritos na sua própria página. Esforço de raciocínio

Limite de saída

max_output_tokens é 4,096 quando você não o envia. É o número de tokens reservado do seu saldo quando a requisição começa; quando a resposta está completa, essa quantidade é substituída pelo que a requisição usou. Um valor que não cabe no seu saldo restante retorna 429 Quota exceeded.

Ele limita o tamanho da resposta em shannon-1.6-*, shannon-2-* e shannon-coder-1, e o tamanho do texto da resposta nos modelos open-weight hospedados.

Neste endpoint, shannon-coder-1 é cobrado em tokens do seu saldo, como qualquer outro modelo.

O corpo de uma requisição pode ter até 32 MiB. Limites e saldo

Erros

Os erros usam o corpo de erro da OpenAI: um objeto error com type e message; alguns também trazem code e param com o valor null. A tabela lista o que este endpoint retorna com mais frequência. A lista completa, com o que tentar de novo, tem a sua própria página. Tratamento de erros