Responses API

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

Y cais lleiaf yw id model a thestun. Nid yw'r ateb yn cael ei ffrydio oni ofynnwch amdano.

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

Gwrthrych ymateb yw'r ateb. Mae ei output yn dal y rhesymu, pan fu'r model yn rhesymu, a'r neges:

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

Meysydd cais

model ac input yw'r hyn sydd ei angen ar gais. Mae'r golofn Wedi'i gymhwyso gan yn enwi'r modelau lle mae maes yn newid yr ateb. Y modelau pwysau agored a gynhelir yw deuddeg id y rhestr fodelau; teulu Shannon 3 yw shannon-3, shannon-3-pro, shannon-3.1 a shannon-3.1-pro. Modelau a phrisiau

Derbynnir previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user a prompt_cache_key fel bod cod cleient presennol yn rhedeg heb newid. Nid ydynt yn newid yr ateb. Gan na chaiff unrhyw sgwrs ei storio, mae cais dilynol yn cario'r troeon cynharach yn input.

Eitemau mewnbwn

Mae eitem fewnbwn naill ai'n neges, gyda role a content, neu'n eitem fathedig sy'n cario galwad offeryn neu ei chanlyniad. Llinyn neu arae o rannau yw content.

Rhowch gyfarwyddiadau yn y maes instructions. Gydag id yn nheulu Shannon 3, rhowch gyfarwyddiadau y mae'n rhaid iddynt ddal yn y neges user.

Gall eitemau output ateb fynd yn ôl i input fel y maent: darllenir eitemau message a function_call, hepgorir eitemau reasoning.

Rhannau cynnwys

Ar haenau Shannon darllenir delweddau a ffeiliau o'r eitem user olaf yn input. Mae gan feintiau a therfynau eu tudalen eu hunain. Delweddau a ffeiliau

Cais gyda chyfarwyddiadau ac opsiynau

Mae'r cais hwn yn anfon cyfarwyddiadau, sgwrs fel eitemau mewnbwn, terfyn allbwn, tymheredd ac ymdrech resymu. Mae'n defnyddio model pwysau agored a gynhelir, sy'n cymhwyso pob un ohonynt.

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

Mae gan ateb model pwysau agored a gynhelir id, object, model, created_at, status, output a usage. Mae ei usage yn ychwanegu'r tokenau a ddarllenwyd o'r cache a'r tokenau a dreuliwyd ar resymu:

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

Y gwrthrych ymateb

Mae id, object, status, output a usage ar bob ateb. Adeiladwch eich cod ar y rheini.

Eitemau allbwn

Mae SDKs OpenAI yn uno testun y neges i chi yn response.output_text.

Ffrydio

Gosodwch stream i true ar gyfer digwyddiadau a anfonir gan y gweinydd. Mae gan bob ffrâm linell event: gydag enw'r digwyddiad a llinell data: gyda gwrthrych JSON; mae'r gwrthrych yn ailadrodd yr enw yn type. Paru deltâu â'u heitem yn ôl output_index.

Gyda SDK OpenAI, darllenwch y digwyddiadau yn ôl eu 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
  }'

Mae'r digwyddiadau'n cyrraedd yn y drefn hon. Mae'r grwpiau ar gyfer rhesymu, y neges a galwadau offer yn ymddangos dim ond pan fo'r ateb yn eu cynnwys.

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

Ffrwd sy'n methu

Ar haenau Shannon mae ateb a fethodd yn gorffen gyda response.failed yn lle response.completed. Ei response.status yw failed ac mae response.error yn dal code, rate_limit_exceeded neu server_error, a message.

Ar y modelau pwysau agored a gynhelir, digwyddiad error yw methiant gyda code api_error a message. Mae response.completed yn dal i'w ddilyn.

Trinnwch ffrwd fel un a fethodd pan fo'n dal response.failed neu ddigwyddiad error, ac anfonwch y cais eto.

Offer

Ffwythiant y mae eich cod yn ei redeg yw offeryn. Disgrifiwch ef yn tools; pan fo'r model ei eisiau, mae'r ateb yn dal eitem function_call yn lle'r neges, neu wrth ei hymyl.

Diffiniad offeryn yn tools:

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

output ateb sy'n ei alw:

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

Rhedwch y ffwythiant, yna anfonwch y cais eto gyda'r alwad a'i chanlyniad wedi'u hychwanegu at 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\"}"
  }
]

Darllenir offer o'r math function yn unig. Ar shannon-1.6-*, shannon-2-* a shannon-coder-1 caiff y sgema parameters ei leihau i allweddeiriau cyffredin JSON Schema: darllenir oneOf fel anyOf, ac nid yw allweddeiriau fel $ref, additionalProperties, const, default a title yn cael eu trosglwyddo i'r model.

Mae'r modelau pwysau agored a gynhelir yn cymhwyso gwerthoedd tool_choice required a ffwythiant a enwir.

Disgrifir y ddolen offer yn llawn ar ei thudalen ei hun. Galw swyddogaeth

Allbwn strwythuredig

Mae'r fformat hwn yn sillafu allbwn strwythuredig fel text.format. Mae'r sgema yn eistedd yn uniongyrchol yn format, wrth ymyl name a strict, nid o dan aelod json_schema fel ar Chat Completions.

• Mae {"type": "json_object"} yn gofyn am unrhyw wrthrych JSON.
• Mae {"type": "json_schema", "name", "schema", "strict"} yn gofyn am JSON sy'n dilyn eich sgema. Mae strict yn true pan fyddwch yn ei adael allan.

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

Mae'r JSON yn cyrraedd fel testun yn rhan output_text y neges; dadansoddwch ef eich hun. Mae model pwysau agored a gynhelir heb allbwn strwythuredig yn dychwelyd 400.

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

Rhestrir pa fodel sy'n cymryd pa ffurf ar ei dudalen ei hun. Allbynnau strwythuredig

Rhesymu

Mae model sy'n rhesymu yn dychwelyd ei resymu fel eitem allbwn o'r math reasoning, cyn y neges. Mewn ffrwd mae'n cyrraedd fel digwyddiadau response.reasoning_summary_text.delta.

Mae'r modelau pwysau agored a gynhelir yn cymhwyso reasoning.effort: off, low, medium neu high, gyda high pan na anfonwch ddim. Nid yw off yn dychwelyd eitem reasoning. Anfonwch ef fel gwrthrych; ni ddarllenir llinyn noeth ar y pwynt terfyn hwn.

Disgrifir yr ymdrechion ar eu tudalen eu hunain. Ymdrech rhesymu

Terfyn allbwn

Mae max_output_tokens yn 4,096 pan na anfonwch ef. Dyna nifer y tokenau a neilltuir o'ch balans pan fo'r cais yn dechrau; pan fo'r ateb yn gyflawn, caiff y swm hwnnw ei ddisodli gan yr hyn a ddefnyddiodd y cais. Mae gwerth nad yw'n ffitio i'ch balans sy'n weddill yn dychwelyd 429 Quota exceeded.

Mae'n cyfyngu hyd yr ateb ar shannon-1.6-*, shannon-2-* a shannon-coder-1, a hyd testun yr ateb ar y modelau pwysau agored a gynhelir.

Ar y pwynt terfyn hwn codir shannon-coder-1 mewn tokenau o'ch balans, fel pob model arall.

Gall corff cais fod hyd at 32 MiB. Terfynau a balans

Gwallau

Mae gwallau'n defnyddio corff gwall OpenAI: gwrthrych error gyda type a message; mae rhai hefyd yn cario code a param gyda'r gwerth null. Mae'r tabl yn rhestru'r hyn y mae'r pwynt terfyn hwn yn ei ddychwelyd amlaf. Mae gan y rhestr lawn, gyda'r hyn i'w ailgeisio, ei thudalen ei hun. Rheoli gwallau