コンテンツへスキップ
Chat Completions

Chat Completions

POST /v1/chat/completions は会話を受け取り、OpenAI Chat Completions 形式でモデルの次のメッセージを返します。OpenAI SDK からでも、素の HTTP からでも使えます。このページはフィールドごとのリファレンスです。

POST https://api.shannon-ai.com/v1/chat/completions

最小のリクエストは、モデル ID とユーザーメッセージひとつです。

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1",
)

response = client.chat.completions.create(
    model="shannon-3",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

print(response.choices[0].message.content)

応答はひとつの JSON オブジェクトです。

200 JSON 
{
  "id": "chatcmpl-5f0c1e7a9b3d4c62a8e1f07d2b46c9a3",
  "object": "chat.completion",
  "created": 1791625200,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello, it is good to meet you.",
        "reasoning_content": "The user wants a greeting in one sentence. Keep it short and friendly."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1184,
    "completion_tokens": 46,
    "total_tokens": 1230
  }
}

ヘッダー

リクエストヘッダー

ヘッダー 値 説明
Authorization Bearer YOUR_API_KEY API キー。すべてのエンドポイントで、代わりに x-api-key: YOUR_API_KEY も使えます。
Content-Type application/json 必須。それ以外の値には 415 が返されます。
x-request-id 任意。リクエストに付ける独自の ID。応答にそのまま返されます。

応答ヘッダー

ヘッダー 説明
x-request-id エラーやストリームを含むすべての応答に付きます。送信した値、または何も送信しなかった場合は十六進数 12 文字の値です。問題を報告するときは、この値を添えてください。
content-type application/json。stream が true の場合は text/event-stream。

リクエストフィールド

必須なのは messages だけです。適用モデル 列は、そのフィールドが応答に影響するモデルを示します。ホスト型オープンウェイトモデルとは、モデルリストにある十二個の ID のことです。Shannon 3 ファミリーは shannon-3、shannon-3-pro、shannon-3.1、shannon-3.1-pro です。 モデルと料金

フィールド 型 デフォルト 説明 適用モデル
model string shannon-1.6-lite 応答するモデル。モデルリストにある ID を指定します。リクエストごとに送信してください。大文字小文字は区別されません。公開されていない ID には 400 の unknown model が返されます。 すべてのモデル
messages array 必須。 会話。古いメッセージから順に並べます。下記の「メッセージ」を参照してください。 すべてのモデル
stream boolean false true を指定すると、応答が書かれている間、server-sent events として送信されます。 すべてのモデル
max_tokens integer 4096 応答の上限（トークン数）。1〜65,536 の範囲外の値は、その範囲内に丸められます。リクエストの実行中に残高から確保しておく量でもあります。下記の「出力の長さ」を参照してください。 ホスト型オープンウェイトモデル、shannon-1.6-lite、shannon-1.6-pro、shannon-coder-1
max_completion_tokens integer max_tokens と同じです。両方を送信した場合は max_tokens が使われます。 ホスト型オープンウェイトモデル、shannon-1.6-lite、shannon-1.6-pro、shannon-coder-1
temperature number サンプリング温度。ホスト型オープンウェイトモデルではデフォルトが 1 で、値は 0〜2 の範囲に収められます。 ホスト型オープンウェイトモデル、shannon-1.6-lite、shannon-1.6-pro、shannon-coder-1
top_p number 0.95 Nucleus サンプリング。値は 0〜1 の範囲に収められます。 ホスト型オープンウェイトモデル
seed integer サンプラーのシード（任意の整数）。指定しない場合、シードはモデルと会話から導出されるため、同じリクエストを二度送信すると同じシードが使われます。 ホスト型オープンウェイトモデル
stop string | array 文字列、または文字列の配列。最大 4 個まで使われます。最初に現れたものの手前で回答が終了し、停止テキスト自体は返されません。 ホスト型オープンウェイトモデル
reasoning_effort string high モデルが回答する前にどれだけ推論するか：off、low、medium、high。none と minimal は off、default は medium、max は high を意味します。それ以外の値には 400 が返されます。 ホスト型オープンウェイトモデル
reasoning object 同じ設定のオブジェクト形式：{"effort": "low"}。両方を送信した場合は reasoning_effort が使われます。 ホスト型オープンウェイトモデル
tools array モデルが呼び出せる関数。それぞれ {"type": "function", "function": {"name", "description", "parameters"}} の形式で指定します。モデルの呼び出しは tool_calls で返され、お使いのコードがそれを実行します。 すべてのモデル
tool_choice string | object auto "auto" はモデルに判断させます。"required" はツールを必ず呼び出させます。{"type": "function", "function": {"name": "…"}} は指定したツールを呼び出させます。 ホスト型オープンウェイトモデル
response_format object JSON の回答には {"type": "json_object"}、スキーマに従う回答には {"type": "json_schema", "json_schema": {…}} を指定します。 すべての Shannon ティア。ホスト型オープンウェイトモデルは ID ごとの一覧のとおり
web_search boolean false true を指定すると、モデルは回答前にウェブを検索できます。 shannon-1.6-*、shannon-2-*、Shannon 3 ファミリー

n、user、stream_options、parallel_tool_calls、presence_penalty、frequency_penalty、logit_bias、logprobs、metadata、store、prompt_cache_key など、その他の OpenAI フィールドは、既存のクライアントコードをそのまま動かせるよう受け付けられます。これらは応答を変えません。選択肢は常にひとつで、ストリームは必ず使用量で終わります。

JSON の型が正しくないフィールド（たとえば "max_tokens": "100"）には 422 が返されます。messages のないリクエストも同様です。

ツール、構造化出力、推論、ウェブ検索には、それぞれ専用のページがあります。 関数呼び出し, 構造化出力, 推論 effort, 内蔵Web検索.

オプション付きのリクエスト

このリクエストは、システムメッセージ、サンプリングフィールド、推論 effort を指定します。これらすべてを適用するホスト型オープンウェイトモデルを使用しています。

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.shannon-ai.com/v1",
)

response = client.chat.completions.create(
    model="DeepSeek-V4-Flash-0731-W4A16-AUTOROUND-REAP",
    messages=[
        {"role": "system", "content": "You are a physics teacher. Answer in two sentences."},
        {"role": "user", "content": "Why is the sky blue?"},
    ],
    max_tokens=512,
    temperature=0.3,
    top_p=0.9,
    seed=7,
    stop=["\n\n"],
    reasoning_effort="low",
)

message = response.choices[0].message
print(message.reasoning_content)  # the reasoning
print(message.content)            # the answer
print(response.usage)

応答の形式は上記と同じです。ホスト型オープンウェイトモデルでは、usage に二つの詳細が加わります：キャッシュから読み取ったプロンプトトークンと、推論に使ったトークンです。

200 JSON 
{
  "usage": {
    "prompt_tokens": 31,
    "completion_tokens": 62,
    "total_tokens": 93,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 21
    }
  }
}

出力の長さ

max_tokens はふたつの働きをします。まず、リクエストの開始時に残高から確保されるトークン数です。応答が完了すると、その量はリクエストが実際に使用したトークン数に置き換えられます。max_tokens が残高の残りより大きい場合、応答自体は収まる長さであっても、リクエストには 429 の Quota exceeded が返されます。確保する量を減らすには、max_tokens を小さくして送信してください。

このエンドポイントでは、shannon-coder-1 は別の方法で計上されます。各リクエストはご利用プランの Shannon Coder 呼び出しの一回分となり、トークンは確保されません。 上限と残高

次に、これらのモデルでは応答の長さを制限します。

モデル max_tokens がどのように働くか
shannon-1.6-lite, shannon-1.6-pro, shannon-coder-1 上限に達すると応答は止まります。ストリームは、finish_reason が length で終了します。
ホスト型オープンウェイトモデル 回答テキストは max_tokens で止まります。推論はこれに含まれません。256 未満の値は 256 として扱われます。

max_tokens も max_completion_tokens もない場合、値は 4,096 です。shannon-coder-1 では 65,536 です。

メッセージ

各メッセージは、role と content を持つオブジェクトです。content は文字列、またはメッセージがテキスト以外も含む場合はパートの配列です。

ロール 説明 適用モデル
system モデルへの指示。先頭に置いてください。Shannon ティアでは、最初の system メッセージが使われます。 ホスト型オープンウェイトモデル、shannon-1.6-*、shannon-2-*、shannon-coder-1
developer system として読み取られます。 ホスト型オープンウェイトモデル
user あなたの質問や依頼。Shannon ティアでは、最後の user メッセージがプロンプトで、それより前のメッセージが履歴です。 すべてのモデル
assistant モデルの以前の応答。その後にツールの結果を送信する場合は、tool_calls を残してください。 すべてのモデル
tool ツール呼び出しの結果：tool_call_id に呼び出しの ID、content に結果を文字列で指定します。 すべてのモデル

Shannon 3 ファミリーの ID では、必ず守らせたい指示を user メッセージに入れてください。

Shannon ティアでは、ユーザーのテキストも tools もないリクエストに 400 の No user message provided が返されます。

コンテンツパート

パート 説明 利用可能なモデル
{"type": "text", "text": "…"} プレーンテキスト。 すべてのモデル
{"type": "image_url", "image_url": {"url": "…"}} 画像。base64 コンテンツの data: URL、または http(s) URL で指定します。 Shannon 3 ファミリー、shannon-1.6-lite、shannon-1.6-pro、および画像入力に対応するホスト型オープンウェイトモデル
{"type": "file", "source": {"type": "base64", "media_type": "application/pdf", "data": "…"}} ドキュメント（PDF、Word、PowerPoint、Excel）。base64 または URL で指定します。 Shannon 3 ファミリー

サイズ、上限、利用できる形式の全一覧には、専用のページがあります。 画像とファイル

応答オブジェクト

フィールド 型 説明
id string chatcmpl- の後ろに 32 桁の十六進数が続きます。
object string 常に chat.completion。
created integer 応答の時刻（Unix 秒）。
model string 応答したモデルの正式な ID。送信した ID とは表記が異なる場合があります。
choices array 選択肢は常にちょうどひとつで、index は 0 です。
choices[0].message.role string 常に assistant。
choices[0].message.content string | null 回答のテキスト。tool_calls がある場合、Shannon ティアでは null です。ホスト型オープンウェイトモデルは、呼び出しと並べてテキストを送信することがあります。
choices[0].message.reasoning_content string | null 回答の前にモデルが書いた推論。ない場合は null です。
choices[0].message.tool_calls array モデルがツールを呼び出す場合にのみ含まれます。各エントリには id、type が function、そして name と JSON 文字列の arguments を持つ function があります。
choices[0].message.annotations array 検索で何かが見つかった web_search: true のリクエストにのみ含まれます。content 内のマーカーが示すソースごとに ひとつの url_citation があり、url、title、start_index、end_index を持ちます（マーカーの位置を文字数で数えた値で、終了位置は含みません）。
choices[0].finish_reason string 応答が終了した理由。「終了理由」を参照してください。
usage object リクエストのトークン。「使用量」を参照してください。
sources array 検索で何かが見つかった web_search: true のリクエストにのみ含まれます。モデルに渡された結果で、それぞれ index、title、url を持ちます。回答中の [1] は index が 1 のエントリです。

終了理由

finish_reason 説明
stop モデルが回答を終えたか、stop の文字列が現れました。
tool_calls モデルがひとつ以上のツールを呼び出します。それらを実行し、結果を tool メッセージで送信してください。
length 応答が出力上限で打ち切られました。shannon-1.6-lite、shannon-1.6-pro、shannon-coder-1、Shannon 3 ファミリーのストリームで報告されます。

ストリームでない応答では、stop または tool_calls が報告されます。

使用量

フィールド 型 説明 利用可能なモデル
usage.prompt_tokens integer 入力トークン。 すべてのモデル
usage.completion_tokens integer 出力トークン：推論、回答、ツール呼び出しの合計。 すべてのモデル
usage.total_tokens integer prompt_tokens と completion_tokens の合計。 すべてのモデル
usage.prompt_tokens_details.cached_tokens integer prompt_tokens のうち、プロンプトキャッシュから読み取られた部分。 ホスト型オープンウェイトモデル
usage.completion_tokens_details.reasoning_tokens integer completion_tokens のうち、推論に使われた部分。 ホスト型オープンウェイトモデル

ホスト型オープンウェイトモデルでは、prompt_tokens は、メッセージとツール定義をモデル独自のトークナイザーで数えた値に、画像のトークンを加えたものです。トークンカウント用エンドポイントは、送信前に同じ数値を返します。 トークンカウント

Shannon ティアでは、prompt_tokens は応答を書くためにモデルが読み取ったすべてを数えるため、メッセージのテキストだけよりも大きくなります。

ストリーミング

stream を true にすると、応答は chat.completion.chunk イベントとして届き、data: [DONE] で終わります。その直前の最後のチャンクに finish_reason と usage が含まれ、stream_options は不要です。チャンクの形式、キープアライブ行、ストリーム内のエラーについては、専用のページがあります。 ストリーミング

エラー

エラーは error メンバーを持つ JSON オブジェクトです。チェックは API キー、リクエストボディ、モデル ID、残高の順に実行されます。表には、このエンドポイントが最もよく返すものを載せています。再試行の可否を含む完全な一覧は、専用のページにあります。 エラー処理

400 JSON 
{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}
ステータス タイプ メッセージ 発生条件
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 ティア：リクエストにユーザーのテキストも tools もありません。
400 invalid_request_error <id> does not accept image input 画像入力に対応していないホスト型オープンウェイトモデルに、画像パートが送信されました。
400 invalid_request_error <id> does not accept response_format 構造化出力に対応していないホスト型オープンウェイトモデルに response_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: … messages がないか、フィールドの JSON 型が正しくありません。
429 rate_limit_error Quota exceeded. Upgrade your plan at shannon-ai.com/plan max_tokens が残高の残りより大きくなっています。
429 rate_limit_error Too many requests. Retry in <n>s. フラッド保護：アカウントで一分間に 120 を超えるリクエストがありました。
500 server_error The model backend failed to answer. Please retry. モデルが応答を生成しませんでした。リクエストをもう一度送信してください。
502 api_error The model backend failed to answer. Please retry. Shannon 3 ファミリーとホスト型オープンウェイトモデルでも同じです。