Claude Messages（识图） - 数字先锋API文档

# Claude Messages（识图）API 文档

## 1. 接口说明
用于向 Claude 多模态模型提交图片并进行理解/描述。
**当前仅支持 base64 方式传图，不支持 image_url 外链直传。**

- **URL**: `POST /v1/messages`
- **Content-Type**: `application/json`
- **Auth**: `Authorization: Bearer {API_KEY}`

---

## 2. 请求参数

### 顶层参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型名，例如 `claude-opus-4-6-thinking` |
| max_tokens | integer | 是 | 最大输出 token 数 |
| messages | array | 是 | 对话消息列表 |

### messages[] 参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| role | string | 是 | 仅支持 `user` |
| content | array | 是 | 多模态内容块（文本+图片） |

### content[]（图片块）
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 是 | 固定为 `image` |
| source.type | string | 是 | 固定为 `base64` |
| source.media_type | string | 是 | `image/jpeg` / `image/png` / `image/webp` |
| source.data | string | 是 | 图片 base64 字符串（**不含** `data:image/...;base64,` 前缀） |

### content[]（文本块）
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 是 | 固定为 `text` |
| text | string | 是 | 提问内容 |

---

## 3. 请求示例（推荐）

```bash
IMG_BASE64=$(base64 -w 0 /path/to/test.jpg)

curl --location --request POST 'https://api.cxsee.com/v1/messages' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw "{
    \"model\": \"claude-opus-4-6-thinking\",
    \"max_tokens\": 512,
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": [
          {
            \"type\": \"image\",
            \"source\": {
              \"type\": \"base64\",
              \"media_type\": \"image/jpeg\",
              \"data\": \"${IMG_BASE64}\"
            }
          },
          {
            \"type\": \"text\",
            \"text\": \"请描述这张图片内容。\"
          }
        ]
      }
    ]
  }"
```

---

## 4. 成功响应示例

```json
{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-6",
  "content": [
    {
      "type": "text",
      "text": "这是一张……"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 1234,
    "output_tokens": 98
  }
}
```

---

## 5. 常见错误与排查

### 5.1 `invalid request parameters`
常见原因：
1. JSON 含注释（`//`）
2. `source.data` 不是完整 base64
3. `media_type` 与真实图片格式不一致
4. body 过大

### 5.2 模型回复“没有看到图片”
说明图片块未被网关识别。
请改用本文档的 `type=image + source.base64` 格式，不要用 `image_url` 外链。

---

## 6. 使用限制建议（可放文档末尾）
- 单图建议 ≤ 5MB（过大先压缩）
- 仅支持 jpg/png/webp
- 鉴权失败返回 401
- 触发风控/配额限制可能返回 429/403

---

上一篇：Claude Messages（对话）下一篇：Claude Messages（思考）