Responses API

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

Cea mai mică cerere este un id de model și un text. Răspunsul nu are streaming dacă nu îl ceri.

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

Răspunsul este un obiect de răspuns. output conține raționamentul, când modelul a raționat, și mesajul:

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

Câmpuri de cerere

model și input sunt ce are nevoie o cerere. Coloana Aplicat de numește modelele pe care un câmp schimbă răspunsul. Modelele open-weight găzduite sunt cele douăsprezece id-uri din lista de modele; familia Shannon 3 este shannon-3, shannon-3-pro, shannon-3.1 și shannon-3.1-pro. Modele și prețuri

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user și prompt_cache_key sunt acceptate pentru ca codul client existent să ruleze neschimbat. Ele nu schimbă răspunsul. Fiindcă nu se stochează nicio conversație, o cerere ulterioară poartă rundele anterioare în input.

Elemente de intrare

Un element de intrare este fie un mesaj, cu role și content, fie un element tipizat care poartă un apel de instrument sau rezultatul lui. content este un șir sau un array de părți.

Pune instrucțiunile în câmpul instructions. Cu un id din familia Shannon 3, pune instrucțiunile care trebuie respectate în mesajul user.

Elementele din output ale unui răspuns se pot întoarce în input așa cum sunt: elementele message și function_call sunt citite, elementele reasoning sunt sărite.

Părți de conținut

La nivelurile Shannon, imaginile și fișierele sunt citite din ultimul element user din input. Mărimile și limitele au pagina lor. Imagini și fișiere

O cerere cu instrucțiuni și opțiuni

Această cerere trimite instrucțiuni, o conversație ca elemente de intrare, o limită de ieșire, o temperatură și un efort de raționament. Folosește un model open-weight găzduit, care le aplică pe toate.

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

Răspunsul unui model open-weight găzduit are id, object, model, created_at, status, output și usage. usage adaugă token-urile citite din cache și token-urile cheltuite pe raționament:

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

Obiectul de răspuns

id, object, status, output și usage sunt în fiecare răspuns. Construiește-ți codul pe acestea.

Elemente de ieșire

SDK-urile OpenAI unesc pentru tine textul mesajului în response.output_text.

Streaming

Setează stream la true pentru server-sent events. Fiecare frame are o linie event: cu numele evenimentului și o linie data: cu un obiect JSON; obiectul repetă numele în type. Asociază delta-urile cu elementul lor după output_index.

Cu SDK-ul OpenAI, citește evenimentele după 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
  }'

Evenimentele sosesc în această ordine. Grupurile pentru raționament, mesaj și apeluri de instrumente apar doar când răspunsul le are.

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 care eșuează

La nivelurile Shannon, un răspuns eșuat se termină cu response.failed în locul lui response.completed. response.status este failed, iar response.error conține un code, rate_limit_exceeded sau server_error, și un message.

La modelele open-weight găzduite, un eșec este un eveniment error cu code api_error și un message. response.completed urmează totuși după el.

Tratează un stream ca eșuat când conține un eveniment response.failed sau error și trimite cererea din nou.

Instrumente

Un instrument este o funcție pe care o rulează codul tău. Descrie-l în tools; când modelul îl vrea, răspunsul conține un element function_call în locul mesajului sau lângă el.

O definiție de instrument în tools:

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

output al unui răspuns care îl apelează:

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

Rulează funcția, apoi trimite din nou cererea, cu apelul și rezultatul lui adăugate în 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\"}"
  }
]

Sunt citite doar instrumentele de tip function. Pe shannon-1.6-*, shannon-2-* și shannon-coder-1, schema parameters este redusă la cuvintele-cheie comune JSON Schema: oneOf este citit ca anyOf, iar cuvinte-cheie precum $ref, additionalProperties, const, default și title nu sunt transmise modelului.

Valorile tool_choice required și o funcție numită sunt aplicate de modelele open-weight găzduite.

Bucla instrumentelor este descrisă complet pe pagina ei. Apelare funcții

Ieșire structurată

Acest format scrie ieșirea structurată ca text.format. Schema stă direct în format, lângă name și strict, nu sub un membru json_schema ca la Chat Completions.

• {"type": "json_object"} cere orice obiect JSON.
• {"type": "json_schema", "name", "schema", "strict"} cere JSON care urmează schema ta. strict este true când îl omiți.

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

JSON-ul sosește ca text în partea output_text a mesajului; parsează-l singur. Un model open-weight găzduit fără ieșire structurată returnează 400.

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

Care model acceptă ce formă este listat pe pagina lui. Rezultate structurate

Raționament

Un model care raționează returnează raționamentul ca element de ieșire de tip reasoning, înaintea mesajului. Într-un stream sosește ca evenimente response.reasoning_summary_text.delta.

Modelele open-weight găzduite aplică reasoning.effort: off, low, medium sau high, cu high când nu trimiți nimic. off nu returnează niciun element de raționament. Trimite-l ca obiect; un șir simplu nu este citit pe acest endpoint.

Eforturile sunt descrise pe pagina lor. Efort de raționament

Limita ieșirii

max_output_tokens este 4,096 când nu îl trimiți. Este numărul de token-uri pus deoparte din soldul tău la începutul cererii; când răspunsul este complet, această sumă este înlocuită cu ce a folosit cererea. O valoare care nu încape în soldul tău rămas returnează 429 Quota exceeded.

Limitează lungimea răspunsului la shannon-1.6-*, shannon-2-* și shannon-coder-1, iar la modelele open-weight găzduite lungimea textului răspunsului.

Pe acest endpoint, shannon-coder-1 este taxat în token-uri din soldul tău, ca orice alt model.

Corpul unei cereri poate avea până la 32 MiB. Limite și sold

Erori

Erorile folosesc corpul de eroare OpenAI: un obiect error cu type și message; unele conțin și code și param cu valoarea null. Tabelul listează ce returnează cel mai des acest endpoint. Lista completă, cu ce trebuie reîncercat, are pagina ei. Gestionare erori