创建聊天识图接口（流式/非流式）

该接口支持多模态输入，允许用户在对话中发送文本以及图片 URL。模型将基于输入的提示语和图像内容生成相应的回复。支持流式（Streaming）输出，以提供更流畅的交互体验。

接口地址: https://api.codingplanx.ai/v1/chat/completions
请求方法: 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`	核采样概率。与 `temperature` 建议仅调整其一。
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	创建时间的时间戳（秒）。
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]。

FAQs (常见问题解答)

Q1: 如何实现图片的上传而不是 URL？ A: 本接口主要支持图片的 URL。如果您只有本地图片，建议先将其上传到您的图床或对象存储（OSS），或者将图片转换为 Base64 编码字符串，格式为 data:image/jpeg;base64,{base64_encode_data} 填入 url 字段中。

Q2: 为什么我的流式请求没有返回 usage 统计？ A: 在标准的 OpenAI 兼容流式协议中，usage 通常只在最后一个数据块或通过设置特殊的 stream_options 参数返回。请检查您的模型版本是否支持在流中返回 Token 计数。

Q3: 图片识图对图片大小和格式有什么限制？ A: 一般支持 PNG, JPEG, WEBP, GIF (非动图)。建议图片大小不超过 20MB。为了获得最佳识别效果，建议分辨率在 512x512 以上。

Q4: 如果我的请求报错 "401 Unauthorized" 怎么办？ A: 请确保您在 Header 中正确传递了 Authorization 字段，格式为 Bearer 加上您的 API KEY，并确保 KEY 是有效的且余额充足。

Q5: temperature 参数对识图有影响吗？ A: 有的。temperature 影响模型描述图片时的语言创造性。如果您需要非常客观、严谨的图片描述，建议设置为较低的值（如 0.2）；如果您希望描述更生动有趣，可以设置为较高的值（如 0.8）。

Q6: 如何处理多张图片的识别？ A: 您可以在 messages.content 数组中放入多个类型为 image_url 的对象，模型会尝试同时理解这些图片的内容。