Chat（分析图片） - 数字先锋API文档

# Chat Completions API（图片分析）
所有对话模型，都可使用此接口， 修改 model 属性为模型名
需要对应的模型支持识图能力如：gpt-4o-image

## 1) 接口地址

```http
POST /v1/chat/completions
```

Base URL:
```text
https://api.cxsee.com
```

完整地址：
```text
https://api.cxsee.com/v1/chat/completions
```

---

## 2) 认证方式

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

---

## 3) 适用模型

支持多模态（图文）输入的 chat 模型，例如：

- `gpt-5.4-mini`（如已开通视觉能力）

> 请以你平台实际开通模型为准。

---

## 4) 请求格式（图片分析）

在 `messages[].content` 中使用数组，混合文本与图片：

- 文本块：`{"type":"text","text":"..."}`
- 图片块：`{"type":"image_url","image_url":{"url":"..."}}`

支持两种图片来源：
1. 公网 URL
```bash
<JSON>
{"type":"image_url","image_url":{"url":"https://example.com/a.jpg"}}
```
2. Base64 Data URL（`data:image/jpeg;base64,...`）
```bash
{"type":"image_url","image_url":{"url":"data:image/png;base64,xxxx"}}
```

---

## 5) 请求示例

### 5.1 使用公网图片 URL

```bash
curl -X POST "https://api.cxsee.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "请描述这张图片的主要内容，并给出3个关键词"},
          {
            "type": "image_url",
            "image_url": {
              "url": "https://example.com/demo.jpg"
            }
          }
        ]
      }
    ]
  }'
```

### 5.2 使用 Base64 图片

```bash
curl -X POST "https://api.cxsee.com/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "识别图片中的物体并输出JSON"},
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
            }
          }
        ]
      }
    ]
  }'
```

## 6) 成功响应示例（非流式）

```json
{
  "id": "chatcmpl-xxxx",
  "object": "chat.completion",
  "created": 1774037000,
  "model": "gpt-5.4-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "这是一张街景照片，画面中有汽车、行人和建筑物。关键词：街道、车辆、城市。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 38,
    "total_tokens": 158
  }
}
```

---

## 7) 流式返回（可选）

图片分析同样支持 `stream: true`：

```json
{
  "model": "gpt-5.4-mini",
  "messages": [...],
  "stream": true
}
```

返回为 SSE（`data: ...` + `data: [DONE]`），按增量拼接 `delta.content`。

---

## 8) 参数建议

- `temperature`：建议 0～0.7（识别类任务建议更低）
- `max_tokens`：根据输出长度设置（如 300/500）
- 可在提示词中要求输出结构化格式（如 JSON）

---

## 9) 错误码

- `400` 参数错误（如 content 格式不合法、图片 URL 无效）
- `401` 认证失败
- `403` 模型无权限或未开通视觉能力
- `413` 图片过大（如网关限制触发）
- `429` 频率超限
- `500/502/503` 服务异常

---

## 10) 对外使用限制建议（可写入文档）

1. 支持 `jpg/jpeg/png/webp`（按平台实际为准）
2. 单张图片大小、分辨率、单次图片数量建议设置上限
3. 图片 URL 需可被服务端访问（非内网地址）
4. 不处理违法违规内容图片，命中策略将拒绝

---

上一篇：Chat（流式返回）下一篇：Chat（工具tools调用）