Responses API

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

La richiesta minima è un id di modello e un testo. La risposta non è in streaming, a meno che tu non lo richieda.

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 risposta è un oggetto response. Il suo output contiene il ragionamento, quando il modello ha ragionato, e il messaggio:

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

Campi della richiesta

model e input sono ciò che serve a una richiesta. La colonna Applicato da indica i modelli su cui un campo cambia la risposta. I modelli open-weight ospitati sono i dodici id dell'elenco dei modelli; la famiglia Shannon 3 è shannon-3, shannon-3-pro, shannon-3.1 e shannon-3.1-pro. Modelli e prezzi

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user e prompt_cache_key vengono accettati affinché il codice client esistente funzioni senza modifiche. Non cambiano la risposta. Poiché nessuna conversazione viene memorizzata, una richiesta successiva porta i turni precedenti in input.

Elementi di input

Un elemento di input è o un messaggio, con un role e un content, oppure un elemento tipizzato che porta una chiamata di tool o il suo risultato. content è una stringa o un array di parti.

Metti le istruzioni nel campo instructions. Con un id della famiglia Shannon 3, metti le istruzioni che devono valere nel messaggio user.

Gli elementi di output di una risposta possono tornare in input così come sono: gli elementi message e function_call vengono letti, gli elementi reasoning vengono saltati.

Parti di contenuto

Sui livelli Shannon immagini e file vengono letti dall'ultimo elemento user di input. Dimensioni e limiti hanno una pagina propria. Immagini e file

Una richiesta con istruzioni e opzioni

Questa richiesta invia istruzioni, una conversazione come elementi di input, un limite di output, una temperatura e un livello di ragionamento. Usa un modello open-weight ospitato, che li applica tutti.

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 risposta di un modello open-weight ospitato ha id, object, model, created_at, status, output e usage. Il suo usage aggiunge i token letti dalla cache e i token spesi in ragionamento:

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

L'oggetto response

id, object, status, output e usage sono presenti in ogni risposta. Costruisci il tuo codice su questi.

Elementi di output

Gli SDK OpenAI uniscono per te il testo del messaggio in response.output_text.

Streaming

Imposta stream su true per i server-sent events. Ogni frame ha una riga event: con il nome dell'evento e una riga data: con un oggetto JSON; l'oggetto ripete il nome in type. Associa i delta al loro elemento tramite output_index.

Con l'SDK OpenAI, leggi gli eventi dal loro 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
  }'

Gli eventi arrivano in questo ordine. I gruppi per il ragionamento, il messaggio e le chiamate di tool compaiono solo quando la risposta li contiene.

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

Uno stream che fallisce

Sui livelli Shannon una risposta fallita termina con response.failed al posto di response.completed. Il suo response.status è failed e response.error contiene un code, rate_limit_exceeded o server_error, e un message.

Sui modelli open-weight ospitati un errore è un evento error con code api_error e un message. response.completed segue comunque.

Considera uno stream fallito quando contiene un evento response.failed o error, e invia di nuovo la richiesta.

Tool

Un tool è una funzione che il tuo codice esegue. Descrivilo in tools; quando il modello lo vuole, la risposta contiene un elemento function_call al posto del messaggio o accanto ad esso.

Una definizione di tool in tools:

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

L'output di una risposta che la chiama:

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

Esegui la funzione, poi invia di nuovo la richiesta con la chiamata e il suo risultato aggiunti 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\"}"
  }
]

Vengono letti solo i tool di tipo function. Su shannon-1.6-*, shannon-2-* e shannon-coder-1 lo schema parameters viene ridotto alle parole chiave comuni di JSON Schema: oneOf viene letto come anyOf, e parole chiave come $ref, additionalProperties, const, default e title non vengono passate al modello.

I valori di tool_choice required e una funzione indicata per nome vengono applicati dai modelli open-weight ospitati.

Il ciclo dei tool è descritto per intero nella sua pagina. Chiamata di funzioni

Output strutturato

Questo formato scrive l'output strutturato come text.format. Lo schema sta direttamente in format, accanto a name e strict, non sotto un membro json_schema come su Chat Completions.

• {"type": "json_object"} richiede un qualsiasi oggetto JSON.
• {"type": "json_schema", "name", "schema", "strict"} richiede JSON conforme al tuo schema. strict è true quando lo ometti.

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

Il JSON arriva come testo nella parte output_text del messaggio; analizzalo tu. Un modello open-weight ospitato senza output strutturato restituisce 400.

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

Quale modello accetta quale forma è elencato nella sua pagina. Output strutturati

Ragionamento

Un modello che ragiona restituisce il proprio ragionamento come elemento di output di tipo reasoning, prima del messaggio. In uno stream arriva come eventi response.reasoning_summary_text.delta.

I modelli open-weight ospitati applicano reasoning.effort: off, low, medium o high, con high quando non invii nulla. off non restituisce alcun elemento di ragionamento. Invialo come oggetto; una semplice stringa non viene letta su questo endpoint.

I livelli di effort sono descritti nella loro pagina. Sforzo di ragionamento

Limite di output

max_output_tokens è 4,096 quando non lo invii. È il numero di token messi da parte dal tuo saldo all'avvio della richiesta; a risposta completa, quella quantità viene sostituita da ciò che la richiesta ha usato. Un valore che non rientra nel saldo residuo restituisce 429 Quota exceeded.

Limita la lunghezza della risposta su shannon-1.6-*, shannon-2-* e shannon-coder-1, e la lunghezza del testo della risposta sui modelli open-weight ospitati.

Su questo endpoint shannon-coder-1 viene addebitato in token dal tuo saldo, come ogni altro modello.

Il corpo di una richiesta può arrivare a 32 MiB. Limiti e saldo

Errori

Gli errori usano il corpo di errore OpenAI: un oggetto error con type e message; alcuni portano anche code e param con il valore null. La tabella elenca ciò che questo endpoint restituisce più spesso. L'elenco completo, con cosa riprovare, ha una pagina propria. Gestione errori