チャット画像認識の作成 (非ストリーミング)

このエンドポイントは、テキストと画像を含むプロンプトをモデルに送信し、1回生成されるチャット補完（Chat Completions）結果を取得するために使用されます。モデルは、入力されたコンテキストと画像内容に基づいて詳細な説明や回答を返します。

エンドポイント URL: https://api.codingplanx.ai/v1/chat/completions
リクエストメソッド: POST
ステータス: リリース済み (Released)

リクエストヘッダー (Headers)

パラメータ名	必須	データ型	サンプル値	説明
Content-Type	はい	String	`application/json`	リクエストボディのフォーマット
Accept	はい	String	`application/json`	レスポンスボディのフォーマット
Authorization	いいえ	String	`Bearer {{YOUR_API_KEY}}`	認証用の API キー

リクエストボディ (Request Body)

パラメータ名	必須	データ型	デフォルト値	説明
model	はい	String	-	使用するモデル ID（例: `gpt-4o`）。
messages	はい	Array	-	会話メッセージのリスト。画像認識を行う場合、`content` にはオブジェクト配列を渡す必要があります。
temperature	いいえ	Number	1	サンプリング温度 (0～2)。高いほどランダムな出力になり、低いほど決定的な出力になります。
top_p	いいえ	Number	1	ヌクレアスサンプリング (Nucleus sampling) の確率。`temperature` との併用は推奨されません（どちらか一方を調整してください）。
max_tokens	いいえ	Integer	inf	生成される最大トークン数。
n	いいえ	Integer	1	各入力に対して生成される代替レスポンスの数。
stream	いいえ	Boolean	false	ストリーミング出力を有効にするかどうか。このエンドポイントでは `false` に固定されます。
stop	いいえ	String/Array	null	生成を停止するトークン。最大4つのシーケンスを指定できます。
presence_penalty	いいえ	Number	0	プレゼンスペナルティ (-2.0 ～ 2.0)。モデルが新しいトピックについて話す可能性を高めます。
frequency_penalty	いいえ	Number	0	フリケンシーペナルティ (-2.0 ～ 2.0)。同じフレーズや言葉を繰り返す可能性を低減させます。
response_format	いいえ	Object	-	出力フォーマットを指定します（例: `{ "type": "json_object" }` で JSON モードを有効化）。
user	いいえ	String	-	エンドユーザーの一意の識別子。
tools	いいえ	Array	-	モデルが呼び出せるツールのリスト（現在 `function` のみサポート）。
tool_choice	いいえ	Object	-	モデルのツール呼び出し動作を制御します（none / auto / 特定の関数を指定）。

messages 画像認識オブジェクト構造 (Content Array)

画像認識リクエストを行う場合、messages.content は以下の構造を含む必要があります：

type: "text" または "image_url"
text: type が text の場合、テキストの質問（プロンプト）を入力します。
image_url: type が image_url の場合、オブジェクト { "url": "画像のURL" } を入力します。

リクエスト例 (Example)

{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "この画像には何が写っていますか？詳細に説明してください。"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://lsky.zhongzhuan.chat/i/2024/10/17/6711068a14527.png"
                    }
                }
            ]
        }
    ]
}

レスポンスパラメータ (Response Body)

パラメータ名	データ型	説明
id	String	このリクエストの一意の識別子。
object	String	オブジェクトタイプ。`chat.completion` で固定されます。
created	Integer	Unix タイムスタンプ (秒)。
choices	Array	生成された複数のレスポンスオプションを含みます。
└ index	Integer	オプションのインデックス番号。
└ message	Object	モデルが返すメッセージオブジェクト（role と content を含む）。
└ finish_reason	String	生成が停止した理由（例: `stop`, `length`）。
usage	Object	トークン使用量の統計データ。
└ prompt_tokens	Integer	プロンプトで消費されたトークン数。
└ completion_tokens	Integer	結果の生成で消費されたトークン数。
└ total_tokens	Integer	消費された合計トークン数。

レスポンス例 (Response)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "この画像は、ノートパソコン、コーヒー、多肉植物が置かれた整頓されたオフィスのデスクを示しています。"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 120,
        "completion_tokens": 45,
        "total_tokens": 165
    }
}

よくある質問 (FAQ)

Q: どのモデルが画像認識（Vision）機能をサポートしていますか？ A: 現在、主に gpt-4o、gpt-4-turbo、および gpt-4-vision-preview などのマルチモーダルモデルをサポートしています。model フィールドに正しい ID を渡していることを確認してください。

Q: サポートされている画像フォーマットは何ですか？ A: PNG、JPEG、WEBP、およびアニメーションではない GIF などの一般的な画像フォーマットをサポートしています。

Q: 画像リンクにアクセス権限の制限はありますか？ A: 提供される画像 URL は、パブリック（公開状態）でアクセス可能である必要があります。画像がプライベートクラウドストレージに保存されている場合は、署名付きの一時アクセスリンクを生成するか、画像を Base64 エンコードに変換してから渡してください（注：Base64 は data:image/jpeg;base64,... のフォーマットに従う必要があります）。

Q: 画像認識のトークン消費（課金）はどのようになりますか？ A: 画像は、その解像度と詳細レベルに基づいてトークンに変換され計算されます。通常、低解像度の画像は固定の少ないトークンを消費し、高解像度の画像は 512x512 のスライス数に基づいてトークンが算出されます。

Q: ストリーミング出力（タイプライター効果）を行いたい場合はどうすればよいですか？ A: リクエストパラメータの stream を true に設定してください。ただし、本ドキュメントは非ストリーミング出力を対象としており、ストリーミング出力時のデータフォーマットは Server-Sent Events (SSE) に変更されることにご注意ください。

Q: なぜ "finish_reason": "length" が返されたのですか？ A: これは、生成されたレスポンスが設定した max_tokens の制限に達したか、モデルのコンテキストウィンドウの制限を超えたため、コンテンツが途中で切り捨てられたことを示しています。