> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yelu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 视觉理解

> 通过 URL 或 Data URI 向支持视觉的模型发送图片与文本。

支持视觉的模型可以同时分析图片和文本。在 Chat Completions 中，发送一个 `content` 数组，其中包含 `text` 与 `image_url` Part。

## 分析图片 URL

将 `IMAGE_URL` 设置为模型供应商可以直接访问的 HTTPS URL。私有图片建议使用短期签名 URL，或在请求大小允许时使用 Data URI。

<CodeGroup>
  ```bash Curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl https://api.yelu.ai/v1/chat/completions \
    -H "Authorization: Bearer $YELU_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"model\":\"gpt-4o-mini\",\"messages\":[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"描述图片并列出可见文字。\"},{\"type\":\"image_url\",\"image_url\":{\"url\":\"$IMAGE_URL\",\"detail\":\"auto\"}}]}],\"max_completion_tokens\":300}"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch('https://api.yelu.ai/v1/chat/completions', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.YELU_API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      model: 'gpt-4o-mini',
      messages: [{ role: 'user', content: [
        { type: 'text', text: '描述图片并列出可见文字。' },
        { type: 'image_url', image_url: { url: process.env.IMAGE_URL, detail: 'auto' } },
      ] }],
      max_completion_tokens: 300,
    }),
  });
  if (!response.ok) throw new Error(await response.text());
  console.log((await response.json()).choices[0].message.content);
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  response = requests.post(
      "https://api.yelu.ai/v1/chat/completions",
      headers={"Authorization": f"Bearer {os.environ['YELU_API_KEY']}"},
      json={
          "model": "gpt-4o-mini",
          "messages": [{"role": "user", "content": [
              {"type": "text", "text": "描述图片并列出可见文字。"},
              {"type": "image_url", "image_url": {"url": os.environ["IMAGE_URL"], "detail": "auto"}},
          ]}],
          "max_completion_tokens": 300,
      },
      timeout=120,
  )
  response.raise_for_status()
  print(response.json()["choices"][0]["message"]["content"])
  ```
</CodeGroup>

## Data URI

本地图片可编码为 `data:image/jpeg;base64,...`。必须使用正确 MIME Type，删除不必要元数据，并在编码前缩放。Base64 会使 Payload 增大约三分之一。

## Detail

* `low`：更快、更便宜，适合粗略分析；
* `high`：适合细节和小字号文字；
* `auto`：由模型选择。

## 安全与隐私

* 验证媒体类型、字节数、像素尺寸和 URL Scheme。
* 如果服务端接收用户 URL，必须阻止内网与 Link-local 地址，防止 SSRF。
* 私有内容使用短期签名 URL，并移除敏感元数据。
* 不要仅依赖视觉模型做身份、医疗、安全或合规决策。

<Note>图片会占用模型上下文并可能单独计费。请将图片缩放到任务需要的分辨率，并以 Dashboard 定价为准。</Note>