# 图像与视觉

区分图片生成与图片理解，再选择对应接口和模型。

## 图片生成

对于模型详情标明支持图片生成接口的模型，可使用 `POST /v1/images/generations`。先把 `XINGSUAN_MODEL` 设为该图片模型的完整 ID。



```bash
curl 'https://api.xsopc.com/v1/images/generations' \
  -H "Authorization: Bearer $XINGSUAN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<JSON
{
  "model": "$XINGSUAN_MODEL",
  "prompt": "A glass pavilion in a forest, soft morning light",
  "n": 1
}
JSON
```



`n`、尺寸、质量及返回格式的支持范围因模型而异。示例只传基础字段；若模型要求尺寸或其他必填项，应按详情补全。

## 生成结果

部分模型同步返回图片 URL 或 Base64，部分模型通过任务方式返回任务 ID。收到任务 ID 后，应查询任务状态，而不是直接把提交响应当作图片结果。结果 URL 可能有有效期，请及时保存到你自己的存储。

## 参考图与图片编辑

`POST /v1/images/edits` 仅适用于支持图片编辑的模型。接口是否接受本地文件、多个文件、Base64 或 URL，由模型和渠道决定。不要假定所有图片模型都能进行图片编辑。

如果上游只支持 URL，客户可自行提供可访问的图片链接；本地文件是否能由平台转换成 URL，取决于平台是否启用对象存储和该模型的上传适配。

## 图片理解

视觉模型通常通过对话接口接收包含图片的消息。下面是请求体结构，请替换视觉模型 ID 和图片 URL，再发送至 `/v1/chat/completions`。



```json
{
  "model": "YOUR_VISION_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Describe this image."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://YOUR_MEDIA_DOMAIN/reference.png"
          }
        }
      ]
    }
  ]
}
```



只有支持视觉输入的模型才能识图。普通文本模型不会因为消息里包含图片链接就自动获得视觉能力。

## 费用核对

生成图片可能按张、按次或按 token 计费，图片理解可能按图片折算 token。以模型详情和调用记录中的计费单位为准；参考图也可能产生输入费用。