创建聊天识图 (非流式)

该接口用于向模型发送包含文本和图片的提示词，并获取单次生成的聊天补全结果。模型将根据输入的上下文及图片内容返回详细的描述或回答。

接口地址: 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	核采样概率。建议与 `temperature` 二选一调整。
max_tokens	否	Integer	inf	生成的最大 Token 数。
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": "图片地址" }。

请求示例 (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	Token 使用统计。
└ prompt_tokens	Integer	提示词消耗的 Token 数。
└ completion_tokens	Integer	结果消耗的 Token 数。
└ total_tokens	Integer	总消耗 Token 数。

响应示例 (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
    }
}

常见问题 (FAQs)

Q: 哪些模型支持识图功能？ 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: 图片会根据其分辨率和细节程度转换为 Token 进行计费。通常低分辨率图片固定消耗少量 Token，高分辨率图片会根据 512x512 的切片数量计算 Token。

Q: 如果我想流式输出（打字机效果）该怎么办？ A: 请将请求参数中的 stream 设置为 true。但请注意，本接口说明针对的是非流式返回，流式返回的数据格式将变为 Server-Sent Events (SSE)。

Q: 为什么返回了 "finish_reason": "length"？ A: 这表示生成的回复达到了您设置的 max_tokens 限制，或者是超过了模型的上下文窗口限制，导致内容被截断。