# 圖像與視覺

區分圖片生成與圖片理解，選擇相符的模型及端點。

## 圖片生成

僅對明確支援的模型使用 `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。請核對模型單位與呼叫紀錄，參考圖也可能產生輸入費用。