Responses API

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

Permintaan terkecil adalah id model dan sebuah teks. Balasan tidak di-stream kecuali 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 adalah objek response. output-nya berisi penalaran, jika model bernalar, dan pesan:

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

Field permintaan

model dan input adalah yang dibutuhkan permintaan. Kolom Applied by menyebutkan model tempat suatu field mengubah balasan. Model open-weight hosted adalah dua belas id dalam daftar model; keluarga Shannon 3 adalah 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 agar kode klien yang ada berjalan tanpa perubahan. Field-field itu tidak mengubah balasan. Karena tidak ada percakapan yang disimpan, permintaan lanjutan membawa giliran sebelumnya di input.

Item input

Item input adalah pesan, dengan role dan content, atau item bertipe yang membawa pemanggilan tool atau hasilnya. content adalah string atau array bagian.

Taruh instruksi di field instructions. Dengan id keluarga Shannon 3, taruh instruksi yang harus dipatuhi di pesan user.

Item dari output balasan dapat dikirim kembali ke input apa adanya: item message dan function_call dibaca, item reasoning dilewati.

Bagian konten

Pada tier Shannon, gambar dan file dibaca dari item user terakhir di input. Ukuran dan batas memiliki halamannya sendiri. Gambar dan file

Permintaan dengan instruksi dan opsi

Permintaan ini mengirim instruksi, percakapan sebagai item input, batas output, temperature, dan reasoning effort. Permintaan ini memakai model open-weight hosted, yang menerapkan semuanya.

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 hosted memiliki id, object, model, created_at, status, output, dan usage. usage-nya menambahkan token yang dibaca dari cache dan token yang dipakai untuk penalaran:

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

Objek response

id, object, status, output, dan usage ada pada setiap balasan. Bangun kode Anda di atasnya.

Item output

SDK OpenAI menggabungkan teks pesan untuk Anda di response.output_text.

Streaming

Setel stream ke true untuk server-sent events. Setiap frame memiliki baris event: berisi nama event dan baris data: berisi objek JSON; objek itu mengulang nama tersebut di type. Cocokkan delta dengan item-nya berdasarkan output_index.

Dengan SDK OpenAI, baca event berdasarkan type-nya:

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

Event datang dalam urutan ini. Kelompok untuk penalaran, pesan, dan pemanggilan tool hanya muncul jika balasan memilikinya.

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 tier Shannon, balasan yang gagal berakhir dengan response.failed sebagai ganti response.completed. response.status-nya adalah failed dan response.error berisi code, yaitu rate_limit_exceeded atau server_error, dan sebuah message.

Pada model open-weight hosted, kegagalan berupa event error dengan code api_error dan sebuah message. response.completed tetap menyusul setelahnya.

Anggap stream gagal jika berisi event response.failed atau error, lalu kirim ulang permintaan.

Tool

Tool adalah fungsi yang dijalankan kode Anda. Deskripsikan di tools; ketika model menginginkannya, balasan berisi item function_call sebagai ganti, atau di samping, pesan.

Definisi tool di 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 fungsinya, lalu kirim permintaan lagi dengan panggilan dan hasilnya ditambahkan ke 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 tool bertipe function yang dibaca. Pada shannon-1.6-*, shannon-2-*, dan shannon-coder-1, skema parameters diringkas menjadi kata kunci JSON Schema yang umum: oneOf dibaca sebagai anyOf, dan kata kunci seperti $ref, additionalProperties, const, default, dan title tidak diteruskan ke model.

Nilai tool_choice required dan fungsi bernama diterapkan oleh model open-weight hosted.

Loop tool dijelaskan lengkap di halamannya sendiri. Pemanggilan fungsi

Output terstruktur

Format ini menuliskan output terstruktur sebagai text.format. Skema berada langsung di format, di samping name dan strict, bukan di bawah anggota json_schema seperti pada Chat Completions.

• {"type": "json_object"} meminta objek JSON apa pun.
• {"type": "json_schema", "name", "schema", "strict"} meminta JSON yang mengikuti skema Anda. strict adalah true jika Anda menghilangkannya.

{
  "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 datang sebagai teks di bagian output_text pada pesan; parse sendiri. Model open-weight hosted tanpa output terstruktur mengembalikan 400.

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

Model mana yang menerima bentuk mana dicantumkan di halamannya sendiri. Output Terstruktur

Penalaran

Model yang bernalar mengembalikan penalarannya sebagai item output bertipe reasoning, sebelum pesan. Dalam stream, penalaran datang sebagai event response.reasoning_summary_text.delta.

Model open-weight hosted menerapkan reasoning.effort: off, low, medium, atau high, dengan high jika Anda tidak mengirim apa pun. off tidak mengembalikan item reasoning. Kirim sebagai objek; string saja tidak dibaca pada endpoint ini.

Level effort dijelaskan di halamannya sendiri. Reasoning effort

Batas output

max_output_tokens adalah 4,096 jika tidak Anda kirim. Itu adalah jumlah token yang disisihkan dari saldo Anda saat permintaan dimulai; ketika balasan selesai, jumlah itu diganti dengan yang dipakai permintaan. Nilai yang tidak muat dalam sisa saldo Anda mengembalikan 429 Quota exceeded.

Ia membatasi panjang balasan pada shannon-1.6-*, shannon-2-*, dan shannon-coder-1, serta panjang teks jawaban pada model open-weight hosted.

Pada endpoint ini, shannon-coder-1 ditagih dalam token dari saldo Anda, seperti model lainnya.

Body permintaan dapat berukuran hingga 32 MiB. Batas dan saldo

Error

Error memakai body error OpenAI: objek error dengan type dan message; sebagian juga membawa code dan param bernilai null. Tabel mencantumkan yang paling sering dikembalikan endpoint ini. Daftar lengkap, beserta mana yang perlu dicoba ulang, ada di halamannya sendiri. Penanganan kesalahan