Responses API

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

Mazākais pieprasījums ir modeļa id un teksts. Atbilde netiek straumēta, ja to nepieprasāt.

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

Atbilde ir atbildes objekts. Tā output satur spriešanu, ja modelis spriedis, un ziņojumu:

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

Pieprasījuma lauki

model un input ir tas, kas pieprasījumam vajadzīgs. Kolonna Piemēro nosauc modeļus, kuriem lauks maina atbildi. Hostētie atvērto svaru modeļi ir divpadsmit modeļu saraksta id; Shannon 3 saime ir shannon-3, shannon-3-pro, shannon-3.1 un shannon-3.1-pro. Modeļi un cenas

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user un prompt_cache_key tiek pieņemti, lai esošais klienta kods darbotos bez izmaiņām. Tie atbildi nemaina. Tā kā neviena saruna netiek glabāta, nākamais pieprasījums nes iepriekšējos gājienus laukā input.

Ievades elementi

Ievades elements ir vai nu ziņojums ar role un content, vai tipizēts elements, kas nes rīka izsaukumu vai tā rezultātu. content ir virkne vai daļu masīvs.

Ievietojiet norādījumus laukā instructions. Ar Shannon 3 saimes id norādījumus, kam jāpastāv, ievietojiet ziņojumā user.

Atbildes output elementus var sūtīt atpakaļ laukā input tādus, kādi tie ir: elementi message un function_call tiek lasīti, elementi reasoning tiek izlaisti.

Satura daļas

Shannon līmeņos attēli un faili tiek lasīti no pēdējā user elementa laukā input. Izmēriem un ierobežojumiem ir sava lapa. Attēli un faili

Pieprasījums ar norādījumiem un opcijām

Šis pieprasījums sūta norādījumus, sarunu kā ievades elementus, izvades ierobežojumu, temperatūru un spriešanas piepūli. Tas izmanto hostētu atvērto svaru modeli, kas piemēro visu minēto.

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

Hostēta atvērto svaru modeļa atbildē ir id, object, model, created_at, status, output un usage. Tā usage papildus rāda no keša nolasītos tokenus un spriešanai iztērētos tokenus:

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

Atbildes objekts

id, object, status, output un usage ir katrā atbildē. Veidojiet savu kodu uz tiem.

Izvades elementi

OpenAI SDK ziņojuma tekstu jūsu vietā savieno laukā response.output_text.

Straumēšana

Iestatiet stream uz true, lai saņemtu servera sūtītus notikumus. Katram kadram ir rinda event: ar notikuma nosaukumu un rinda data: ar JSON objektu; objekts atkārto nosaukumu laukā type. Saskaņojiet delta ar to elementu pēc output_index.

Ar OpenAI SDK lasiet notikumus pēc to 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
  }'

Notikumi ierodas šādā secībā. Spriešanas, ziņojuma un rīku izsaukumu grupas parādās tikai tad, ja atbildē tās ir.

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

Straume, kas neizdodas

Shannon līmeņos neizdevusies atbilde beidzas ar response.failed response.completed vietā. Tās response.status ir failed, un response.error satur code, rate_limit_exceeded vai server_error, un message.

Hostētajiem atvērto svaru modeļiem kļūme ir notikums error ar code api_error un message. Tam tāpat seko response.completed.

Uzskatiet straumi par neizdevušos, ja tajā ir response.failed vai notikums error, un nosūtiet pieprasījumu vēlreiz.

Rīki

Rīks ir funkcija, ko palaiž jūsu kods. Aprakstiet to laukā tools; kad modelis to vēlas, atbildē ir elements function_call ziņojuma vietā vai līdzās tam.

Rīka definīcija laukā tools:

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

Atbildes output, kas to izsauc:

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

Palaidiet funkciju, tad nosūtiet pieprasījumu vēlreiz, pievienojot izsaukumu un tā rezultātu laukam 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\"}"
  }
]

Tiek lasīti tikai rīki ar tipu function. Modeļiem shannon-1.6-*, shannon-2-* un shannon-coder-1 shēma parameters tiek sašaurināta līdz parastajiem JSON Schema atslēgvārdiem: oneOf tiek lasīts kā anyOf, un atslēgvārdi, piemēram, $ref, additionalProperties, const, default un title, modelim netiek nodoti.

tool_choice vērtības required un nosaukta funkcija piemēro hostētie atvērto svaru modeļi.

Rīku cikls pilnībā aprakstīts savā lapā. Funkciju izsaukšana

Strukturēta izvade

Šis formāts strukturētu izvadi raksta kā text.format. Shēma atrodas tieši laukā format, blakus name un strict, nevis zem locekļa json_schema, kā galapunktā Chat Completions.

• {"type": "json_object"} pieprasa jebkuru JSON objektu.
• {"type": "json_schema", "name", "schema", "strict"} pieprasa JSON, kas seko jūsu shēmai. strict ir true, ja to izlaižat.

{
  "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 ierodas kā teksts ziņojuma daļā output_text; parsējiet to pats. Hostēts atvērto svaru modelis bez strukturētas izvades atgriež 400.

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

Kurš modelis pieņem kuru formu, ir uzskaitīts savā lapā. Strukturēti izvadi

Spriešana

Modelis, kas spriež, atgriež savu spriešanu kā izvades elementu ar tipu reasoning pirms ziņojuma. Straumē tā ierodas kā notikumi response.reasoning_summary_text.delta.

Hostētie atvērto svaru modeļi piemēro reasoning.effort: off, low, medium vai high, ar high, ja nesūtāt neko. off neatgriež spriešanas elementu. Sūtiet to kā objektu; vienkārša virkne šajā galapunktā netiek lasīta.

Piepūles līmeņi ir aprakstīti savā lapā. Spriešanas apjoms

Izvades ierobežojums

max_output_tokens ir 4,096, ja to nesūtāt. Tas ir tokenu skaits, ko atliek malā no jūsu atlikuma, kad pieprasījums sākas; kad atbilde ir pilnīga, šī summa tiek aizstāta ar to, ko pieprasījums izmantoja. Vērtība, kas neietilpst jūsu atlikušajā atlikumā, atgriež 429 Quota exceeded.

Tas ierobežo atbildes garumu modeļiem shannon-1.6-*, shannon-2-* un shannon-coder-1 un atbildes teksta garumu hostētajiem atvērto svaru modeļiem.

Šajā galapunktā shannon-coder-1 tiek rēķināts tokenos no jūsu atlikuma, tāpat kā katrs cits modelis.

Pieprasījuma pamatteksts var būt līdz 32 MiB. Ierobežojumi un atlikums

Kļūdas

Kļūdas izmanto OpenAI kļūdas pamattekstu: objekts error ar type un message; dažas nes arī code un param ar vērtību null. Tabula uzskaita to, ko šis galapunkts atgriež visbiežāk. Pilns saraksts, norādot, ko atkārtot, ir savā lapā. Kļūdu apstrāde