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

# 图片理解 API：用 GPT-6 与 Gemini 分析图片和 PDF

> 在老张API用 GPT-6、GPT-5.6 与 Gemini 模型分析图片和 PDF：Chat Completions 与 Responses 的 URL、Base64、多图、detail 与文件写法，以及音频、视频输入该走哪个接口。

图片理解让多模态模型读图后用文字回答，适合截图问答、票据识别、界面检查和图片对比。同一个请求格式可以调用 GPT-6、GPT-5.6 和 Gemini 模型，只需改 `model`。

| 项目 | 内容 |
| - | - |
| 端点 | `POST https://api.laozhang.ai/v1/chat/completions` |
| 请求写法 | 在一条 `user` 消息的 `content` 数组里放入 `text` 和 `image_url` 内容块 |
| 图片来源 | 公网图片地址，或 Base64 data URL |
| 读取回答 | `choices[0].message.content` |
| 本页示例模型 | `gpt-6-sol` |

## 选择模型

以下模型都在 `default` 分组按量计费，单价见[模型与价格总表](/models)：

| 厂商 | 模型 ID | 适合 |
| - | - | - |
| OpenAI | `gpt-6-astra` | 最复杂的图片与文档推理，单价最高 |
| OpenAI | `gpt-6-sol`、`gpt-5.6-terra` | 通用图片与文档理解 |
| OpenAI | `gpt-6-luna` | 批量截图问答、分类等成本敏感任务 |
| Google | `gemini-3.8-flash`、`gemini-3.7-flash`、`gemini-3.5-flash-lite` | 图片理解，以及需要音频、视频输入的任务 |
| Google | `gemini-3.1-pro-preview` | 需要更强推理的复杂图片与文档 |

`qwen3-vl-plus` 等 Qwen VL 模型也接受 `image_url` 图片请求，但要求图片 URL 的响应带 `Content-Length` 头，否则返回 400 `Missing Content-Length of multimodal url`。本页示例截图的地址不满足这一条件，用 Qwen 时请改用 Base64。

不同模型能接收的输入类型不同，PDF、音频和视频要走对应的接口：

| 输入 | OpenAI 模型 | Gemini 模型 |
| - | - | - |
| 图片 | Chat Completions、Responses | Chat Completions、[Gemini 原生接口](/api-reference/gemini#发送图片内容) |
| PDF | Chat Completions、Responses，见[读取 PDF 文件](#读取-pdf-文件) | 仅 [Gemini 原生接口](/api-reference/gemini#发送-pdf-和音频) |
| 音频 | 不接受；转文字用[音频转录接口](/api-capabilities/audio-transcription) | 仅 [Gemini 原生接口](/api-reference/gemini#发送-pdf-和音频) |
| 视频 | 不接受 | [视频理解 API](/api-capabilities/video-understanding) |

## 准备密钥

在[令牌管理](https://api.laozhang.ai/token)创建 API Key，计费模式选择按量优先（推荐）或按量计费，然后写入环境变量。使用 Python 示例时，先执行 `python -m pip install openai`。

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
```

## 使用图片 URL

示例图片是老张API控制台「令牌管理」页面的截图，问题是让模型找出截图中用红框标出的按钮：

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --fail-with-body --max-time 120 \
      "https://api.laozhang.ai/v1/chat/completions" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-6-sol",
        "messages": [{
          "role": "user",
          "content": [
            {"type": "text", "text": "图中红框标出了哪些按钮？请用一句话回答。"},
            {"type": "image_url", "image_url": {"url": "https://docs.laozhang.ai/images/key-manage.png"}}
          ]
        }]
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ["LAOZHANG_API_KEY"],
        base_url="https://api.laozhang.ai/v1",
        timeout=120.0,
        max_retries=0,
    )
    response = client.chat.completions.create(
        model="gpt-6-sol",
        messages=[{
            "role": "user",
            "content": [
                {"type": "text", "text": "图中红框标出了哪些按钮？请用一句话回答。"},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://docs.laozhang.ai/images/key-manage.png"},
                },
            ],
        }],
    )
    print(response.choices[0].message.content)
    ```
  </Tab>
</Tabs>

回答应指出「新增」和「复制」两个按钮。换成 `gemini-3.8-flash` 等其他模型时，只改 `model`。

换成自己的图片时，URL 必须能从公网直接打开，不能依赖登录状态或 Cookie，否则模型读取不到图片。

## 上传本地图片

图片不在公网上时，把文件编码为 Base64，拼成 `data:<MIME 类型>;base64,<数据>` 形式的 data URL，放进同一个 `image_url.url` 字段。以下示例读取当前目录中的 `input.png`：

```python theme={null}
import base64
import mimetypes
import os
from pathlib import Path
from openai import OpenAI

image_path = Path("input.png")
mime_type = mimetypes.guess_type(image_path.name)[0] or "image/png"
data_url = f"data:{mime_type};base64," + base64.b64encode(
    image_path.read_bytes()
).decode("ascii")

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=120.0,
    max_retries=0,
)
response = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "请描述这张图片的主要内容。"},
            {"type": "image_url", "image_url": {"url": data_url}},
        ],
    }],
)
print(response.choices[0].message.content)
```

data URL 中的 MIME 类型要与文件的实际格式一致，例如 JPEG 图片写 `data:image/jpeg;base64,`。

## 一次发送多张图片

在同一条消息的 `content` 里依次放多个 `image_url` 内容块，模型会按顺序读取，可以用来对比两个版本或跨图汇总信息。在提示词里说明图片顺序（例如「第一张」「第二张」），回答会更准确。

```python theme={null}
import base64
import os
from pathlib import Path
from openai import OpenAI

def to_data_url(path: str) -> str:
    data = base64.b64encode(Path(path).read_bytes()).decode("ascii")
    return f"data:image/png;base64,{data}"

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=120.0,
    max_retries=0,
)
response = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "第一张是修改前，第二张是修改后。请列出两张图的所有差异。"},
            {"type": "image_url", "image_url": {"url": to_data_url("before.png")}},
            {"type": "image_url", "image_url": {"url": to_data_url("after.png")}},
        ],
    }],
)
print(response.choices[0].message.content)
```

## 控制图片精度

OpenAI 模型支持在 `image_url` 中加 `detail`，用来在识别细节和 token 用量之间取舍：

| 取值 | 效果 |
| - | - |
| `auto` | 默认值，由模型决定 |
| `low` | 以低分辨率处理，输入 token 明显减少，适合判断图片大意或分类 |
| `high` | 以高分辨率处理，适合读取小字、表格和密集界面 |

```json theme={null}
{"type": "image_url", "image_url": {"url": "https://docs.laozhang.ai/images/key-manage.png", "detail": "low"}}
```

Gemini 模型会忽略 `detail`，token 用量不变。

## 读取 PDF 文件

OpenAI 模型可以直接读取 PDF，不需要先转成图片。把 PDF 编码为 Base64 data URL，放进 `file` 内容块，并填写 `filename`：

```python theme={null}
import base64
import os
from pathlib import Path
from openai import OpenAI

pdf_data = base64.b64encode(Path("invoice.pdf").read_bytes()).decode("ascii")

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=120.0,
    max_retries=0,
)
response = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "这张发票的编号、应付总额和到期日分别是什么？"},
            {
                "type": "file",
                "file": {
                    "filename": "invoice.pdf",
                    "file_data": f"data:application/pdf;base64,{pdf_data}",
                },
            },
        ],
    }],
)
print(response.choices[0].message.content)
```

PDF 的每一页都会被读取，跨页的信息也能回答。

<Warning>
  **Gemini 模型在 Chat Completions 中不会读取 `file` 内容块。**

  * 请求仍返回 200，但 PDF 被忽略，模型会回答「没有收到附件」或凭空作答。
  * 用 Gemini 分析 PDF 时，改用 [Gemini 原生接口](/api-reference/gemini#发送-pdf-和音频)。
</Warning>

## 使用 Responses API

OpenAI 模型也可以用 [Responses API](/api-manual#responses-api) 传图片和 PDF，内容块类型分别是 `input_image` 和 `input_file`：

```python theme={null}
import base64
import os
from pathlib import Path
from openai import OpenAI

pdf_data = base64.b64encode(Path("invoice.pdf").read_bytes()).decode("ascii")

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
    timeout=120.0,
    max_retries=0,
)
response = client.responses.create(
    model="gpt-6-sol",
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "图中红框标出了哪些按钮？再说出发票的编号。"},
            {"type": "input_image", "image_url": "https://docs.laozhang.ai/images/key-manage.png"},
            {
                "type": "input_file",
                "filename": "invoice.pdf",
                "file_data": f"data:application/pdf;base64,{pdf_data}",
            },
        ],
    }],
)
print(response.output_text)
```

`input_image` 的 `image_url` 是字符串，可以是公网 URL 或 Base64 data URL。Gemini 模型不支持 Responses API，请使用 Chat Completions 或 Gemini 原生接口。

## 读取结果

模型的回答是普通文本，位于 `choices[0].message.content`，响应结构与 OpenAI 协议的文本回复相同。需要边生成边显示时，加上 `"stream": true`，图片请求同样支持流式输出。

`usage.prompt_tokens` 包含图片和文件占用的 token，实际费用以[调用日志](/faq/call-logs)为准。

图片理解可能遗漏或误读细节，例如把相近的数字读错。涉及金额、编号、法律、医疗、财务、身份等重要判断时，请保留人工复核。

## 使用 Gemini 原生接口

Gemini 模型用原生 `generateContent` 格式时，除了图片，还能读取 PDF、音频和视频：

* 图片：见 [Gemini 协议：发送图片内容](/api-reference/gemini#发送图片内容)。
* PDF 与音频：见 [Gemini 协议：发送 PDF 和音频](/api-reference/gemini#发送-pdf-和音频)。
* MP4 视频（画面与音轨）：见[视频理解 API](/api-capabilities/video-understanding)。

## 常见问题

### 哪个模型识别图片最准？

复杂界面、小字和多图对比优先用 `gpt-6-sol` 或 `gpt-6-astra`。批量、简单的识别任务可以用 `gpt-6-luna` 或 `gemini-3.5-flash-lite` 降低成本。上线前用自己的图片比较几个候选模型的准确度和 token 用量。

### 能直接传 PDF 吗？

可以。OpenAI 模型用 Chat Completions 的 `file` 内容块或 Responses 的 `input_file`，示例见[读取 PDF 文件](#读取-pdf-文件)。Gemini 模型需要用 [Gemini 原生接口](/api-reference/gemini#发送-pdf-和音频)，Chat Completions 中的 PDF 会被忽略。

### 能把音频发给模型吗？

GPT-6 和 GPT-5.6 不接受音频输入，发送 `input_audio` 会返回 400。只需要转文字时用[音频转录接口](/api-capabilities/audio-transcription)。需要模型直接听音频并回答问题时，用 Gemini 模型的[原生接口](/api-reference/gemini#发送-pdf-和音频)。

### 能传视频吗？

OpenAI 模型不接受视频。Gemini 模型可以通过原生接口分析 MP4 的画面和音轨，也可以在 Chat Completions 中用 `video_url` 传 Base64 data URL，示例见[视频理解 API](/api-capabilities/video-understanding)。

### 模型说没有收到图片或文件怎么办？

先看 `usage.prompt_tokens`：如果只有几十个 token，说明附件没有被读取。常见原因：

* 图片 URL 需要登录或已失效；
* data URL 的 MIME 类型与文件不符，或 Base64 不完整；
* 给 Gemini 模型用了 `file` 或 `input_audio` 内容块，这两种在 Chat Completions 中会被忽略。

### 图片怎么计费？

图片和 PDF 都换算成输入 token，与文字一起按模型单价计费。OpenAI 模型把 `detail` 设为 `low` 能明显减少图片 token，Gemini 模型不受 `detail` 影响。每次请求的 token 数与费用见[调用日志](/faq/call-logs)。

## 相关文档

* [OpenAI 图片输入指南](https://developers.openai.com/api/docs/guides/images-vision)
* [OpenAI 文件输入指南](https://developers.openai.com/api/docs/guides/pdf-files)
* [OpenAI 协议](/api-reference/chat-completions)
* [Gemini 协议](/api-reference/gemini)
* [视频理解 API](/api-capabilities/video-understanding)
* [音频转录与语音生成](/api-capabilities/audio-transcription)
* [模型与价格总表](/models)
* [数据与日志边界](/faq/data-security)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.