Responses API-a

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

Eskaerarik txikienak modelo id bat eta testu bat ditu. Erantzuna ez da streamean bidaltzen, hala eskatzen ez baduzu.

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

Erantzuna response objektu bat da. Bere output-ak arrazonamendua dauka, modeloak arrazoitu badu, eta mezua:

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

Eskaera-eremuak

model eta input dira eskaera batek behar duena. Aplikatzen duena zutabeak eremu batek erantzuna aldatzen duen modeloak adierazten ditu. Pisu irekiko modelo ostatatuak modelo-zerrendako hamabi id dira; Shannon 3 familia shannon-3, shannon-3-pro, shannon-3.1 eta shannon-3.1-pro da. Modeloak eta prezioak

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user eta prompt_cache_key onartzen dira, lehendik dagoen bezero-kodea aldatu gabe ibil dadin. Ez dute erantzuna aldatzen. Elkarrizketarik gordetzen ez denez, ondorengo eskaera batek aurreko txandak input-ean darama.

Sarrera-elementuak

Sarrera-elementu bat mezu bat da, role eta content dituena, edo tresna-dei bat edo haren emaitza daraman elementu tipatu bat. content kate bat da edo zati-array bat.

Jarri jarraibideak instructions eremuan. Shannon 3 familiako id batekin, jarri bete behar diren jarraibideak user mezuan.

Erantzun baten output-eko elementuak bere horretan itzul daitezke input-era: message eta function_call elementuak irakurtzen dira, reasoning elementuak saltatzen dira.

Eduki-zatiak

Shannon mailetan, irudiak eta fitxategiak input-eko azken user elementutik irakurtzen dira. Tamainek eta mugek beren orrialdea dute. Irudiak eta fitxategiak

Jarraibideak eta aukerak dituen eskaera

Eskaera honek jarraibideak, elkarrizketa sarrera-elementu gisa, irteera-muga bat, tenperatura bat eta arrazonamendu-esfortzu bat bidaltzen ditu. Pisu irekiko modelo ostatatu bat erabiltzen du, eta horrek guztiak aplikatzen ditu.

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

Pisu irekiko modelo ostatatu baten erantzunak id, object, model, created_at, status, output eta usage ditu. Bere usage-k cache-tik irakurritako tokenak eta arrazonamenduan erabilitako tokenak gehitzen ditu:

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

Response objektua

id, object, status, output eta usage erantzun guztietan daude. Oinarritu zure kodea horietan.

Irteera-elementuak

OpenAI SDKek mezuaren testua zuretzat elkartzen dute response.output_text atalean.

Streaminga

Ezarri stream true gisa server-sent events jasotzeko. Frame bakoitzak gertaeraren izena duen event: lerro bat eta JSON objektu bat duen data: lerro bat ditu; objektuak izena errepikatzen du type-n. Lotu deltak beren elementuarekin output_index bidez.

OpenAI SDKrekin, irakurri gertaerak beren type bidez:

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

Gertaerak ordena honetan iristen dira. Arrazonamenduaren, mezuaren eta tresna-deien taldeak erantzunak dituenean bakarrik agertzen dira.

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

Huts egiten duen stream bat

Shannon mailetan, huts egindako erantzun bat response.failed-ekin amaitzen da, response.completed-en ordez. Bere response.status failed da eta response.error-ek code bat dauka, rate_limit_exceeded edo server_error, eta message bat.

Pisu irekiko modelo ostatatuetan hutsegitea error gertaera bat da, code api_error eta message batekin. response.completed hala ere hurrena dator.

Hartu stream bat huts egin duela response.failed edo error gertaera bat duenean, eta bidali eskaera berriro.

Tresnak

Tresna bat zure kodeak exekutatzen duen funtzio bat da. Deskribatu tools-en; modeloak nahi duenean, erantzunak function_call elementu bat dauka, mezuaren ordez edo mezuaren ondoan.

Tresna baten definizioa tools-en:

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

Hura deitzen duen erantzun baten output-a:

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

Exekutatu funtzioa, eta bidali eskaera berriro deia eta bere emaitza input-era gehituta:

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

function motako tresnak bakarrik irakurtzen dira. shannon-1.6-*, shannon-2-* eta shannon-coder-1-en parameters eskema JSON Schema-ren gako arruntetara murrizten da: oneOf anyOf gisa irakurtzen da, eta $ref, additionalProperties, const, default eta title bezalako gakoak ez zaizkio modeloari pasatzen.

tool_choice-ren required balioa eta izendatutako funtzio bat pisu irekiko modelo ostatatuek aplikatzen dituzte.

Tresna-begizta osorik bere orrian azaltzen da. Funtzio-deiak

Irteera egituratua

Formatu honek irteera egituratua text.format gisa idazten du. Eskema zuzenean format-ean dago, name eta strict-en ondoan, ez json_schema kide baten azpian, Chat Completions-en bezala.

• {"type": "json_object"}-k edozein JSON objektu eskatzen du.
• {"type": "json_schema", "name", "schema", "strict"}-k zure eskema betetzen duen JSON eskatzen du. strict true da kanpoan uzten baduzu.

{
  "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 testu gisa iristen da mezuaren output_text zatian; parseatu zuk zeuk. Irteera egituraturik gabeko pisu irekiko modelo ostatatu batek 400 itzultzen du.

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

Zein modelok zer forma onartzen duen bere orrian zerrendatzen da. Irteera egituratuak

Arrazonamendua

Arrazoitzen duen modelo batek bere arrazonamendua reasoning motako irteera-elementu gisa itzultzen du, mezuaren aurretik. Stream batean response.reasoning_summary_text.delta gertaera gisa iristen da.

Pisu irekiko modelo ostatatuek reasoning.effort aplikatzen dute: off, low, medium edo high, eta high ezer bidaltzen ez baduzu. off-ek ez du arrazonamendu-elementurik itzultzen. Bidali objektu gisa; kate hutsa ez da irakurtzen endpoint honetan.

Esfortzuak beren orrian azaltzen dira. Arrazonamendu-esfortzua

Irteera-muga

max_output_tokens 4,096 da bidaltzen ez baduzu. Eskaera hasten denean zure saldotik bereizten den token kopurua da; erantzuna osatzen denean, kopuru hori eskaerak erabilitakoarekin ordezkatzen da. Zure gainerako saldoan sartzen ez den balio batek 429 Quota exceeded itzultzen du.

Erantzunaren luzera mugatzen du shannon-1.6-*, shannon-2-* eta shannon-coder-1 modeloetan, eta erantzun-testuaren luzera pisu irekiko modelo ostatatuetan.

Endpoint honetan shannon-coder-1 tokenetan kobratzen da zure saldotik, beste modelo guztiak bezala.

Eskaera-gorputzak 32 MiB arte izan dezake. Mugak eta saldoa

Erroreak

Erroreek OpenAI errore-gorputza erabiltzen dute: type eta message dituen error objektu bat; batzuek code eta param ere badituzte null balioarekin. Taulak endpoint honek maizen itzultzen duena zerrendatzen du. Zerrenda osoak, zer berriz saiatu behar den adierazita, bere orrialdea du. Errore‑kudeaketa