API Responses

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

Permintaan terkecil ialah id model dan satu teks. Balasan tidak di-stream melainkan anda memintanya.

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

Balasan ialah objek respons. outputnya memegang penaakulan, apabila model bernalar, dan mesej:

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

Medan permintaan

model dan input ialah apa yang diperlukan oleh permintaan. Lajur Dikenakan oleh menamakan model yang medannya mengubah balasan. Model open-weight yang dihoskan ialah dua belas id dalam senarai model; keluarga Shannon 3 ialah shannon-3, shannon-3-pro, shannon-3.1 dan shannon-3.1-pro. Model & harga

previous_response_id, store, metadata, parallel_tool_calls, truncation, include, user dan prompt_cache_key diterima supaya kod klien sedia ada berjalan tanpa perubahan. Ia tidak mengubah balasan. Oleh sebab tiada perbualan disimpan, permintaan susulan membawa giliran terdahulu dalam input.

Item input

Item input sama ada mesej, dengan role dan content, atau item bertaip yang membawa panggilan alat atau keputusannya. content ialah rentetan atau tatasusunan bahagian.

Letakkan arahan dalam medan instructions. Dengan id keluarga Shannon 3, letakkan arahan yang mesti dipatuhi dalam mesej user.

Item output balasan boleh dihantar kembali ke dalam input seadanya: item message dan function_call dibaca, item reasoning dilangkau.

Bahagian kandungan

Pada peringkat Shannon, imej dan fail dibaca daripada item user yang terakhir dalam input. Saiz dan had mempunyai halamannya sendiri. Imej dan fail

Permintaan dengan arahan dan pilihan

Permintaan ini menghantar arahan, perbualan sebagai item input, had output, suhu dan usaha penaakulan. Ia menggunakan model open-weight yang dihoskan, yang menggunakan kesemuanya.

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

Balasan model open-weight yang dihoskan mempunyai id, object, model, created_at, status, output dan usage. usagenya menambah token yang dibaca daripada cache dan token yang digunakan untuk penaakulan:

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

Objek respons

id, object, status, output dan usage terdapat pada setiap balasan. Bina kod anda berdasarkan medan itu.

Item output

SDK OpenAI menggabungkan teks mesej untuk anda dalam response.output_text.

Streaming

Tetapkan stream kepada true untuk server-sent events. Setiap bingkai mempunyai baris event: dengan nama peristiwa dan baris data: dengan objek JSON; objek itu mengulang nama dalam type. Padankan delta dengan itemnya melalui output_index.

Dengan SDK OpenAI, baca peristiwa mengikut typenya:

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

Peristiwa tiba mengikut urutan ini. Kumpulan untuk penaakulan, mesej dan panggilan alat muncul hanya apabila balasan mempunyainya.

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

Stream yang gagal

Pada peringkat Shannon, balasan yang gagal berakhir dengan response.failed sebagai ganti response.completed. response.statusnya ialah failed dan response.error memegang code, rate_limit_exceeded atau server_error, dan message.

Pada model open-weight yang dihoskan, kegagalan ialah peristiwa error dengan code api_error dan message. response.completed masih menyusul selepasnya.

Anggap stream gagal apabila ia memegang peristiwa response.failed atau error, dan hantar semula permintaan.

Alat

Alat ialah fungsi yang dijalankan oleh kod anda. Huraikannya dalam tools; apabila model mahukannya, balasan memegang item function_call sebagai ganti, atau di sebelah, mesej.

Takrifan alat dalam tools:

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

output balasan yang memanggilnya:

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

Jalankan fungsi, kemudian hantar permintaan sekali lagi dengan panggilan dan keputusannya ditambah pada 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\"}"
  }
]

Hanya alat berjenis function dibaca. Pada shannon-1.6-*, shannon-2-* dan shannon-coder-1, skema parameters dikurangkan kepada kata kunci JSON Schema yang lazim: oneOf dibaca sebagai anyOf, dan kata kunci seperti $ref, additionalProperties, const, default dan title tidak diteruskan kepada model.

Nilai tool_choice required dan fungsi yang dinamakan dikenakan oleh model open-weight yang dihoskan.

Gelung alat diterangkan sepenuhnya pada halamannya sendiri. Panggilan Fungsi

Output berstruktur

Format ini mengeja output berstruktur sebagai text.format. Skema terletak terus dalam format, di sebelah name dan strict, bukan di bawah ahli json_schema seperti pada Chat Completions.

• {"type": "json_object"} meminta sebarang objek JSON.
• {"type": "json_schema", "name", "schema", "strict"} meminta JSON yang mengikut skema anda. strict ialah true apabila anda tidak menyertakannya.

{
  "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 tiba sebagai teks dalam bahagian output_text mesej; huraikannya sendiri. Model open-weight yang dihoskan tanpa output berstruktur memulangkan 400.

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

Model mana yang menerima bentuk mana disenaraikan pada halamannya sendiri. Output Berstruktur

Penaakulan

Model yang bernalar memulangkan penaakulannya sebagai item output berjenis reasoning, sebelum mesej. Dalam stream, ia tiba sebagai peristiwa response.reasoning_summary_text.delta.

Model open-weight yang dihoskan menggunakan reasoning.effort: off, low, medium atau high, dengan high apabila anda tidak menghantar apa-apa. off tidak memulangkan item penaakulan. Hantar sebagai objek; rentetan sahaja tidak dibaca pada endpoint ini.

Tahap usaha diterangkan pada halamannya sendiri. Usaha penaakulan

Had output

max_output_tokens ialah 4,096 apabila anda tidak menghantarnya. Ia ialah bilangan token yang diketepikan daripada baki anda apabila permintaan bermula; apabila balasan lengkap, jumlah itu digantikan dengan apa yang digunakan oleh permintaan. Nilai yang tidak muat dalam baki anda yang tinggal memulangkan 429 Quota exceeded.

Ia mengehadkan panjang balasan pada shannon-1.6-*, shannon-2-* dan shannon-coder-1, dan panjang teks jawapan pada model open-weight yang dihoskan.

Pada endpoint ini, shannon-coder-1 dicaj dalam token daripada baki anda, seperti setiap model lain.

Badan permintaan boleh sehingga 32 MiB. Had dan baki

Ralat

Ralat menggunakan badan ralat OpenAI: objek error dengan type dan message; sesetengahnya turut membawa code dan param dengan nilai null. Jadual menyenaraikan apa yang paling kerap dipulangkan oleh endpoint ini. Senarai penuh, dengan apa yang perlu dicuba semula, mempunyai halamannya sendiri. Pengendalian Ralat