Responses API
新規POST /v1/responses は、指示と入力アイテムのリストを受け取り、OpenAI Responses 形式で、出力アイテムからなるレスポンスオブジェクトを返します。OpenAI SDK の responses API や、Codex CLI のようにそれを基にしたツールで使えます。このエンドポイントは状態を保持しません。リクエストごとに会話全体を送信してください。
POST https://api.shannon-ai.com/v1/responses
最小のリクエストは、モデル ID とテキストです。要求しない限り、応答はストリームされません。
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."
}' 応答はレスポンスオブジェクトです。その output には、モデルが推論した場合は推論と、メッセージが入ります。
{
"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
}
} リクエストフィールド
リクエストに必要なのは model と input です。適用モデル 列は、そのフィールドが応答に影響するモデルを示します。ホスト型オープンウェイトモデルとは、モデルリストにある十二個の ID のことです。Shannon 3 ファミリーは shannon-3、shannon-3-pro、shannon-3.1、shannon-3.1-pro です。 モデルと料金
| フィールド | 型 | デフォルト | 説明 | 適用モデル |
|---|---|---|---|---|
model | string | 必須。 モデルリストにある ID。大文字小文字は区別されません。ID がない、または公開されていない場合は、400 の unknown model が返されます。 | すべてのモデル | |
input | string | array | 文字列(ユーザーメッセージひとつとして読み取られます)、または入力アイテムの配列。下記の「入力アイテム」を参照してください。 | すべてのモデル | |
instructions | string | モデルへの指示。この形式でのシステムプロンプトです。 | ホスト型オープンウェイトモデル、shannon-1.6-*、shannon-2-*、shannon-coder-1 | |
stream | boolean | false | true を指定すると、応答を server-sent events として送信します。下記の「ストリーミング」を参照してください。 | すべてのモデル |
max_output_tokens | integer | 4096 | 応答の上限(トークン数)。1〜65,536 の範囲外の値は、その範囲内に丸められます。リクエストの実行中に残高から確保しておく量でもあります。下記の「出力の上限」を参照してください。 | ホスト型オープンウェイトモデル、shannon-1.6-*、shannon-2-*、shannon-coder-1 |
temperature | number | サンプリング温度。ホスト型オープンウェイトモデルでは、値は 0〜2 の範囲に収められます。 | ホスト型オープンウェイトモデル。ストリームでない応答では shannon-1.6-*、shannon-2-*、shannon-coder-1 | |
top_p | number | Nucleus サンプリング。値は 0〜1 の範囲に収められます。 | ホスト型オープンウェイトモデル | |
tools | array | モデルが呼び出せる関数。この形式のフラットな形で指定します:{"type": "function", "name", "description", "parameters"}。下記の「ツール」を参照してください。 | すべてのモデル | |
tool_choice | string | object | auto | "auto" はモデルに判断させます。"required" はツールを必ず呼び出させます。{"type": "function", "name": "…"} は指定したツールを呼び出させます。 | ホスト型オープンウェイトモデル |
reasoning | object | off、low、medium、high を指定した {"effort": "…"}。それ以外の値には 400 が返されます。 | ホスト型オープンウェイトモデル | |
text | object | {"format": {…}} で JSON の回答を要求します。下記の「構造化出力」を参照してください。 | すべての Shannon ティア。ホスト型オープンウェイトモデルは ID ごとの一覧のとおり |
previous_response_id、store、metadata、parallel_tool_calls、truncation、include、user、prompt_cache_key は、既存のクライアントコードをそのまま動かせるよう受け付けられます。これらは応答を変えません。会話は保存されないため、後続のリクエストは、それ以前のターンを input に含めます。
入力アイテム
入力アイテムは、role と content を持つメッセージか、ツール呼び出しやその結果を運ぶ型付きアイテムのどちらかです。content は文字列、またはパートの配列です。
| アイテム | 説明 | 適用モデル |
|---|---|---|
{"role": "user", "content": …} | あなたの質問や依頼。content は文字列、または input_text と input_image のパートです。 | すべてのモデル |
{"role": "assistant", "content": …} | モデルの以前の応答。content は文字列、または output_text パートです。 | すべてのモデル |
{"role": "system", "content": …}{"role": "developer", "content": …} | 会話内の指示。 | ホスト型オープンウェイトモデル |
{"type": "function_call", "call_id": "…", "name": "…", "arguments": "…"} | モデルが以前の応答で行ったツール呼び出し。arguments は JSON 文字列です。 | すべてのモデル |
{"type": "function_call_output", "call_id": "…", "output": "…"} | その呼び出しの結果。call_id は呼び出しの ID、output は文字列としての結果です。 | すべてのモデル |
指示は instructions フィールドに入れてください。Shannon 3 ファミリーの ID では、必ず守らせたい指示を user メッセージに入れてください。
応答の output のアイテムは、そのまま input に戻せます。message と function_call アイテムは読み取られ、reasoning アイテムはスキップされます。
コンテンツパート
| パート | 説明 | 利用可能なモデル |
|---|---|---|
{"type": "input_text", "text": "…"} | ユーザーメッセージのテキスト。 | すべてのモデル |
{"type": "output_text", "text": "…"} | アシスタントメッセージのテキスト。 | すべてのモデル |
{"type": "input_image", "image_url": "…"} | 画像。base64 コンテンツの data: URL、または http(s) URL で指定します。 | Shannon 3 ファミリー、shannon-1.6-lite、shannon-1.6-pro、および画像入力に対応するホスト型オープンウェイトモデル |
{"type": "input_file", "file_data": "data:application/pdf;base64,…"} | ドキュメント(PDF、Word、PowerPoint、Excel):file_data に data: URL、または file_url に http(s) URL を指定します。 | Shannon 3 ファミリー |
Shannon ティアでは、画像とファイルは input の最後の user アイテムから読み取られます。サイズと上限については別のページを参照してください。 画像とファイル
指示とオプション付きのリクエスト
このリクエストは、指示、入力アイテムとしての会話、出力上限、temperature、推論 effort を送信します。これらすべてを適用するホスト型オープンウェイトモデルを使用しています。
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"}
}' ホスト型オープンウェイトモデルの応答には、id、object、model、created_at、status、output、usage があります。その usage には、キャッシュから読み取ったトークンと、推論に使ったトークンが加わります。
{
"usage": {
"input_tokens": 58,
"input_tokens_details": {
"cached_tokens": 0
},
"output_tokens": 67,
"output_tokens_details": {
"reasoning_tokens": 19
},
"total_tokens": 125
}
} レスポンスオブジェクト
id、object、status、output、usage はすべての応答に含まれます。コードはこれらを前提に組み立ててください。
| フィールド | 型 | 説明 | 送信元 |
|---|---|---|---|
id | string | resp_ の後ろに 32 桁の十六進数が続きます。 | すべてのモデル |
object | string | 常に response。 | すべてのモデル |
status | string | completed。ストリームでは最初は in_progress で、response.failed イベントでは failed です。 | すべてのモデル |
output | array | モデルが生成した順の出力アイテム:reasoning、message、function_call。 | すべてのモデル |
usage | object | input_tokens、output_tokens、total_tokens。 | すべてのモデル |
usage.input_tokens_details | object | cached_tokens:プロンプトキャッシュから読み取られた入力トークン。 | ホスト型オープンウェイトモデル |
usage.output_tokens_details | object | reasoning_tokens:推論に使われた出力トークン。 | ホスト型オープンウェイトモデル |
model | string | 応答したモデルの正式な ID。 | Shannon 3 ファミリー、ホスト型オープンウェイトモデル |
created_at | integer | 応答の時刻(Unix 秒)。 | Shannon 3 ファミリー、ホスト型オープンウェイトモデル |
instructions, tools, temperature, … | instructions、tools、temperature はリクエストの値を繰り返します。error と incomplete_details は null、metadata は {}、parallel_tool_calls は true、tool_choice は auto、top_p は null です。 | Shannon 3 ファミリー |
出力アイテム
| アイテム | 説明 |
|---|---|
{"id": "rs_…", "type": "reasoning", "summary": [{"type": "summary_text", "text": "…"}]} | モデルの推論を、ひとつの summary_text パートとして表したもの。モデルが推論した場合にのみ含まれます。 |
{"id": "msg_…", "type": "message", "role": "assistant", "content": [{"type": "output_text", "text": "…"}]} | 回答:テキストを含むひとつの output_text パート。 |
{"id": "fc_…", "type": "function_call", "call_id": "call_…", "name": "…", "arguments": "…"} | ツール呼び出し。arguments は JSON 文字列です。結果は同じ call_id を付けて送り返してください。 |
OpenAI SDK は、メッセージのテキストを response.output_text に連結して提供します。
ストリーミング
server-sent events を使うには stream を true に設定します。各フレームには、イベント名を示す event: 行と、JSON オブジェクトを含む data: 行があり、オブジェクトは type に同じ名前を持ちます。デルタは output_index で対応するアイテムに結び付けてください。
OpenAI SDK では、イベントを 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
}' イベントは次の順序で届きます。推論、メッセージ、ツール呼び出しのグループは、応答にそれらが含まれる場合にのみ現れます。
| イベント | ペイロード | 発生条件 |
|---|---|---|
response.created | response | 常に最初。response.status は in_progress で、response.output は空です。 |
response.in_progress | response | 常に二番目。同じオブジェクトです。 |
response.output_item.added | output_index, item | 推論の開始:空の summary を持つ reasoning アイテム。 |
response.reasoning_summary_text.delta | output_index, summary_index, delta | 推論の一部。 |
response.reasoning_summary_text.done | output_index, summary_index, text | 推論の完了:その全体の text。 |
response.output_item.done | output_index, item | 完成した reasoning アイテム。 |
response.output_item.added | output_index, item | 回答の開始:ステータスが in_progress で、内容のない message アイテム。 |
response.content_part.added | output_index, content_index, part | 空の output_text パートが開きます。 |
response.output_text.delta | output_index, content_index, delta | 回答の一部。 |
response.output_text.done | output_index, content_index, text | 回答の完了:その全体の text。 |
response.content_part.done | output_index, content_index, part | 完成した output_text パート。 |
response.output_item.done | output_index, item | 完成した message アイテム。ステータスは completed です。 |
response.output_item.added | output_index, item | ツール呼び出しの開始:call_id、name、空の arguments を持つ function_call アイテム。 |
response.function_call_arguments.delta | output_index, delta | 呼び出しの引数。ひとつのデルタに全体が含まれます。 |
response.function_call_arguments.done | output_index, arguments | 同じ引数を arguments として。 |
response.output_item.done | output_index, item | 完成した function_call アイテム。 |
response.completed | response | 成功時は常に最後:output と usage を含むレスポンスオブジェクト全体。 |
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}, …}} 失敗するストリーム
Shannon ティアでは、失敗した応答は response.completed の代わりに response.failed で終わります。その response.status は failed で、response.error には code(rate_limit_exceeded または server_error)と message が入ります。
ホスト型オープンウェイトモデルでは、失敗は code が api_error で message を持つ error イベントです。その後にも response.completed が続きます。
ストリームに response.failed または error イベントが含まれる場合は失敗として扱い、リクエストを再送信してください。
ツール
ツールは、お使いのコードが実行する関数です。tools で記述すると、モデルがそれを必要とした場合、応答にはメッセージの代わりに、またはメッセージと並べて、function_call アイテムが含まれます。
tools 内のツール定義:
[
{
"type": "function",
"name": "get_weather",
"description": "Current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
},
"required": [
"city"
]
}
}
] ツールを呼び出す応答の output:
[
{
"id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
"type": "function_call",
"name": "get_weather",
"call_id": "call_3d9a7c1e5b2f4a60c8e1d7f09b24a6c5",
"arguments": "{\"city\":\"Paris\"}"
}
] 関数を実行し、呼び出しとその結果を 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\"}"
}
] タイプ function のツールだけが読み取られます。shannon-1.6-*、shannon-2-*、shannon-coder-1 では、parameters スキーマは一般的な JSON Schema キーワードに絞り込まれます。oneOf は anyOf として読み取られ、$ref、additionalProperties、const、default、title などのキーワードはモデルに渡されません。
tool_choice の値 required と名前付き関数は、ホスト型オープンウェイトモデルで適用されます。
ツールループの詳細は、専用のページで説明しています。 関数呼び出し
構造化出力
この形式では、構造化出力を text.format で指定します。スキーマは、Chat Completions のような json_schema メンバーの下ではなく、format 内の name と strict の隣に直接置きます。
{"type": "json_object"}は、任意の JSON オブジェクトを要求します。{"type": "json_schema", "name", "schema", "strict"}は、スキーマに従う JSON を要求します。省略した場合、strictはtrueです。
{
"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 は、メッセージの output_text パートにテキストとして届くので、自分でパースしてください。構造化出力に対応していないホスト型オープンウェイトモデルは 400 を返します。
{"city": "Lisbon", "date": "2027-05-12"} どのモデルがどの形式を受け付けるかは、専用のページに一覧があります。 構造化出力
推論
推論するモデルは、メッセージの前に、タイプ reasoning の出力アイテムとして推論を返します。ストリームでは response.reasoning_summary_text.delta イベントとして届きます。
ホスト型オープンウェイトモデルは reasoning.effort を適用します:off、low、medium、high。何も送信しない場合は high です。off では reasoning アイテムは返されません。オブジェクトとして送信してください。このエンドポイントでは、単独の文字列は読み取られません。
effort の詳細は専用のページで説明しています。 推論 effort
出力の上限
max_output_tokens を送信しない場合は 4,096 です。これはリクエストの開始時に残高から確保されるトークン数で、応答が完了すると、その量はリクエストが実際に使用した量に置き換えられます。残りの残高に収まらない値には、429 の Quota exceeded が返されます。
shannon-1.6-*、shannon-2-*、shannon-coder-1 では応答の長さを、ホスト型オープンウェイトモデルでは回答テキストの長さを制限します。
このエンドポイントでは、shannon-coder-1 は他のモデルと同様に、残高からトークンで課金されます。
リクエストボディは最大 32 MiB までです。 上限と残高
エラー
エラーは OpenAI のエラーボディ形式を使います。type と message を持つ error オブジェクトで、一部は値が null の code と param も含みます。表には、このエンドポイントが最もよく返すものを載せています。再試行の可否を含む完全な一覧は、専用のページにあります。 エラー処理
| ステータス | タイプ | メッセージ | 発生条件 |
|---|---|---|---|
401 | authentication_error | Missing authenticationInvalid API key | API キーが送信されていないか、キーが不明または無効化されています。 |
400 | invalid_request_error | unknown model: <id> | model がないか、公開されている ID ではありません。 |
400 | invalid_request_error | No user message provided. | Shannon ティア:input にユーザーのテキストがありません。 |
400 | invalid_request_error | <id> does not accept image input | 画像入力に対応していないホスト型オープンウェイトモデルに画像が送信されました。 |
400 | invalid_request_error | <id> does not accept response_format | 構造化出力に対応していないホスト型オープンウェイトモデルに text.format が送信されました。 |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | reasoning.effort に、一覧にない値が指定されています。 |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | ボディは有効な JSON ですが、フィールドの型が正しくありません。 |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | max_output_tokens が残高の残りより大きくなっています。 |
429 | rate_limit_error | Too many requests. Retry in <n>s. | フラッド保護:アカウントで一分間に 120 を超えるリクエストがありました。 |
500 | api_error | The model backend failed to answer. Please retry. | モデルが応答を生成しませんでした。リクエストをもう一度送信してください。 |
502 | api_error | The model backend failed to answer. Please retry. | ホスト型オープンウェイトモデルでも同じです。 |
504 | api_error | upstream timed out | ホスト型オープンウェイトモデルが、ストリームでない応答の制限時間を超えました。stream を true にして送信してください。 |