画像認識チャットAPIの作成（ストリーミング / 非ストリーミング対応）

このエンドポイントはマルチモーダル入力に対応しており、対話の中でテキストおよび画像URLを送信できます。モデルは入力されたプロンプトと画像コンテンツに基づいて適切な応答を生成します。ストリーミング（Streaming）出力に対応しており、よりスムーズな対話体験を提供します。

エンドポイントURL: https://api.codingplanx.ai/v1/chat/completions
HTTPメソッド: POST
公式リファレンス: OpenAI Chat Completion API

リクエストパラメータ

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

ボディ（Body）パラメータ

パラメータ名	型	必須	デフォルト値	説明
model	string	はい	-	使用するモデルID（例: `gpt-4o`, `gpt-4-vision-preview`）。
messages	array	はい	-	これまでの対話メッセージのリスト。詳細は後述の `messages` 構造を参照。
stream	boolean	いいえ	`false`	ストリーミング出力を有効にするかどうか。有効にした場合、Server-Sent Events (SSE) が送信されます。
temperature	number	いいえ	`1`	サンプリング温度 (0〜2)。値が高いほどランダム性が増し、低いほど決定論的になります。
top_p	number	いいえ	`1`	ヌクレアスサンプリング（Nucleus sampling）の確率。`temperature` か `top_p` のどちらか一方のみを変更することを推奨します。
max_tokens	integer	いいえ	inf	チャット補完で生成される最大トークン数。
n	integer	いいえ	`1`	各入力メッセージに対して生成する回答（選択肢）の数。
presence_penalty	number	いいえ	`0`	(-2.0 から 2.0) 正の値にすると、モデルが新しいトピックについて話す可能性が高くなります。
frequency_penalty	number	いいえ	`0`	(-2.0 から 2.0) 正の値にすると、モデルが同じ単語を繰り返す可能性が低くなります。
response_format	object	いいえ	-	出力フォーマットを指定します（例: `{"type": "json_object"}`）。
stop	string/array	いいえ	null	トークンの生成を停止するシーケンス（最大4つ）。
user	string	いいえ	-	不正利用を監視するための、エンドユーザーの一意の識別子。

messages オブジェクトの構造

メッセージリストの各項目には以下のフィールドが含まれます：

role: (string) ロール。system, user, assistant, tool から選択可能。
content: (string または array) メッセージの内容。
- 画像認識モードの場合、content は配列となり、text および image_url タイプのオブジェクトを含みます。

リクエスト例

テキストと画像認識の複合リクエスト (JSON)

{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "あなたはプロフェッショナルな画像分析アシスタントです。"
      },
      {
            "role": "user",
            "content": [
                {
                    "type": "text", 
                    "text": "この画像には何が写っていますか？詳細に説明してください。"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image.png"
                    }
                }
            ]
        }
    ],
    "stream": true
}

レスポンスに関する説明

非ストリーミングレスポンス (stream: false)

パラメータ名	型	説明
id	string	リクエストの一意の識別子。
object	string	オブジェクトタイプ。通常は `chat.completion`。
created	integer	作成日時のタイムスタンプ（UNIX秒）。
choices	array	モデルが生成した選択肢のリスト。
choices[n].message	object	モデルが返すメッセージオブジェクト（`role` と `content` を含む）。
choices[n].finish_reason	string	停止理由（例: `stop`, `length`）。
usage	object	トークン使用量の統計。

レスポンス例

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "この画像には静かな湖が写っており、背景には連なる山々が見えます。"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 120,
        "completion_tokens": 35,
        "total_tokens": 155
    }
}

ストリーミングレスポンス (stream: true)

stream が true の場合、エンドポイントは text/event-stream を返します。各行は data: で始まり、内容はJSON文字列となります。最後のメッセージは data: [DONE] として送信されます。

よくある質問 (FAQ)

Q1: URLの代わりに画像を直接アップロードするにはどうすればよいですか？ A: 本エンドポイントは主に画像URLに対応しています。ローカル画像のみをお持ちの場合は、先に画像ホスティングサービスやオブジェクトストレージ（OSS）にアップロードするか、画像を Base64 エンコード文字列に変換し、data:image/jpeg;base64,{base64_encode_data} の形式で url フィールドに入力することをお勧めします。

Q2: ストリーミングリクエストで usage（トークン統計）が返されないのはなぜですか？ A: 標準的なOpenAI互換のストリーミングプロトコルでは、通常 usage は最後のデータチャンクに含まれるか、または特別な stream_options パラメータを設定することで返されます。お使いのモデルのバージョンがストリーミング中のトークンカウント出力に対応しているかご確認ください。

Q3: 画像認識における画像のサイズやフォーマットに制限はありますか？ A: 一般的に PNG, JPEG, WEBP, GIF（アニメーション不可）に対応しています。画像サイズは20MB以下を推奨します。最適な認識精度を得るためには、解像度を 512x512 以上にすることをお勧めします。

Q4: リクエストで "401 Unauthorized" エラーが発生した場合、どうすればよいですか？ A: ヘッダーの Authorization フィールドに、Bearer とAPIキーが正しいフォーマットで渡されているか確認してください。また、APIキーが有効であり、アカウントの残高（クレジット）が十分にあることを確認してください。

Q5: temperature パラメータは画像認識に影響しますか？ A: はい、影響します。temperature は、モデルが画像を説明する際の言語の創造性に影響を与えます。非常に客観的で厳密な画像説明が必要な場合は、低い値（例: 0.2）に設定することをお勧めします。より鮮やかで興味深い説明を求める場合は、高い値（例: 0.8）に設定できます。

Q6: 複数の画像を一度に認識させるにはどうすればよいですか？ A: messages.content 配列内に image_url タイプのオブジェクトを複数含めることで、モデルはそれら複数の画像コンテンツを同時に理解しようと試みます。