コンテンツへスキップ
Responses API

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)

応答はレスポンスオブジェクトです。その output には、モデルが推論した場合は推論と、メッセージが入ります。

200 JSON
{
  "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)

ホスト型オープンウェイトモデルの応答には、id、object、model、created_at、status、output、usage があります。その usage には、キャッシュから読み取ったトークンと、推論に使ったトークンが加わります。

200 JSON
{
  "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")

イベントは次の順序で届きます。推論、メッセージ、ツール呼び出しのグループは、応答にそれらが含まれる場合にのみ現れます。

イベント ペイロード 発生条件
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 を含むレスポンスオブジェクト全体。
200 text/event-stream
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 内のツール定義:

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

ツールを呼び出す応答の output:

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

関数を実行し、呼び出しとその結果を input に追加して、もう一度リクエストを送信します。

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 です。
POST /v1/responses
{
  "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 を返します。

output_text
{"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 authentication
Invalid 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 にして送信してください。