# 媒体输入与 URL 获取

AISIX 会将模型请求中的图片、音频和文件输入转换为所选上游所需的格式。内联数据会保持内联。远程 URL 会直接发送给能够读取它的上游，或由网关下载并嵌入服务提供方原生请求。

此行为适用于 `/v1/chat/completions`、使用 Chat 转换的 `/v1/messages` 和 `/v1/responses` 请求，以及 Amazon Bedrock 和 Google Vertex AI 上的原生 Claude Messages 路由。AISIX 会根据所选服务提供方和媒体类型决定使用哪条路径。

## 了解支持的媒体路径[​](#了解支持的媒体路径 "了解支持的媒体路径的直接链接")

AISIX 会为 Anthropic、Amazon Bedrock 和 Google Vertex AI 适配器转换 `image_url`、`input_audio` 和 `file` 内容。Bedrock 的 InvokeModel 和 Converse 路径对所有模型都执行转换。在 Vertex AI 上，转换适用于 Claude 和 Gemini。兼容 OpenAI 的适配器会按调用方发送的原样转发这些内容。

| 输入                                                                                              | AISIX 发送到上游的内容                                                                                                                                             |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 内联数据，例如 `data:` URL、`input_audio` 或 `file.file_data`                                     | 服务提供方原生的内联媒体块。                                                                                                                                       |
| 发送到 Anthropic API 的 `https://` URL                                                            | 原始 URL，因为 Anthropic 可以自行读取。                                                                                                                            |
| 发送到 Gemini 的 `gs://` 或 `https://` URL，且调用方明确指定了媒体类型或 URL 扩展名指明了媒体类型 | 原始 URL，因为 Gemini 可以自行读取。                                                                                                                               |
| 通过原生服务提供方适配器发送的其他任意 `http://` 或 `https://` URL                                | AISIX 下载内容并内联发送。这包括所有 Bedrock 模型、Vertex AI 上的 Claude、发送到 Anthropic 或 Gemini 的 `http://` URL，以及 Gemini 无法识别类型的 `https://` URL。 |
| 所选上游无法读取的 scheme，例如发送到 Bedrock 的 `gs://`                                          | 请求以 `400` 拒绝。                                                                                                                                                |

上游无法接受的内容会以 `400` 拒绝，并以 `messages[i].content[j]` 指明其位置；AISIX 绝不会静默丢弃。例如，Claude 模型接受图片和 PDF 文档，但不接受音频。

对于下载的 URL，AISIX 按以下顺序识别媒体类型：

1. 调用方提供的 `format`、`mime_type` 或 `content_type`。
2. 响应的 `Content-Type`，但不包括 `application/octet-stream` 或 `binary/*`。
3. URL 扩展名。
4. 下载的内容。

如果这些方式都无法识别类型，AISIX 会以 `400` 拒绝请求。

## 控制 AISIX 可以获取的 URL[​](#控制-aisix-可以获取的-url "控制 AISIX 可以获取的 URL的直接链接")

媒体 URL 由 API 调用方提供，因此网关下载受 `outbound.ssrf_protection` 约束。该防护默认启用。除非 `allowed_hosts` 豁免该主机，否则 AISIX 会检查主机解析出的每个地址以及每一跳重定向，最多检查 10 跳。

防护启用时，AISIX 会拒绝环回地址、私有地址（RFC 1918）、运营商级 NAT、链路本地地址、文档和基准测试地址、多播地址、保留地址、IPv6 唯一本地地址和 IPv6 链路本地地址，其中包括 `169.254.169.254` 元数据端点。直连只会使用 AISIX 已检查的地址。

如果 AISIX 应当访问某个主机而不受其地址限制，请在 `outbound.ssrf_protection.allowed_hosts` 中列出该主机；也可以将 `outbound.ssrf_protection.enabled` 设为 `false` 以关闭检查。

透明代理或 Fake-IP DNS 服务可能把公网主机解析到 `198.18.0.0/15`，而 AISIX 会将其视为基准测试地址段。在这类环境中，请把媒体主机加入 `allowed_hosts`，或关闭该防护。

### 正向代理与 TLS[​](#正向代理与-tls "正向代理与 TLS的直接链接")

除非 `NO_PROXY` 覆盖该主机，否则媒体下载会使用 `HTTPS_PROXY`、`HTTP_PROXY` 或 `ALL_PROXY`。SSRF 防护启用且主机不在允许列表中时，AISIX 会先解析并检查主机，再把请求交给代理。因此，即使代理能够访问，网关本地无法解析的主机也会被拒绝。当网关无法在本地解析主机时，请将其加入 `allowed_hosts`，或关闭该防护。

下载会信任 `upstream.tls.ca_file` 中的证书颁发机构，并遵循 `upstream.tls.verify`。下载绝不会出示上游客户端证书，也不会转发调用方的请求头。

## 配置媒体获取[​](#配置媒体获取 "配置媒体获取的直接链接")

在网关启动配置中配置下载：

config.yaml（媒体 URL 下载）

```
upstream:

  media_fetch:

    enabled: true

    max_bytes: 52428800

outbound:

  ssrf_protection:

    enabled: true

    allowed_hosts: ["media.internal", "10.0.0.5:9000"]
```

❶ 媒体获取默认启用。将该字段设为 `false` 后，如果所选上游无法读取某个 URL，AISIX 会以 `400` 拒绝该 URL。

❷ 下载限制适用于每个 URL，默认值为 50 MiB。

❸ SSRF 防护默认启用。将该字段设为 `false` 会关闭地址检查并忽略允许列表。

❹ 每个允许列表条目可以是主机（允许任意端口）或 `host:port`。带端口的 IPv6 地址应写作 `[addr]:port`。条目无效时，网关会在启动时停止。

如需通过环境变量配置地址控制，请使用 `AISIX_OUTBOUND__SSRF_PROTECTION__ENABLED` 和 `AISIX_OUTBOUND__SSRF_PROTECTION__ALLOWED_HOSTS`。列表应写为逗号分隔的值：

```
AISIX_OUTBOUND__SSRF_PROTECTION__ALLOWED_HOSTS="media.internal,10.0.0.5:9000"
```

该环境变量不接受 JSON 数组；使用 JSON 数组会导致网关在启动时停止。

SSRF 设置只约束 API 调用方提供的 URL，目前即媒体下载。运维人员配置的 URL，例如服务提供方密钥的 `api_base`、安全护栏、MCP、A2A、JWKS 或导出器端点，不受该设置检查。

## 了解下载限制[​](#了解下载限制 "了解下载限制的直接链接")

每个媒体 URL 都受 `upstream.media_fetch.max_bytes` 限制。同一请求中的所有下载还会与入站请求体一起计入 `proxy.request_body_limit_bytes`。超过单个 URL 的限制会返回 `400`；超过请求合计限制会返回 `413`。详见[限制请求体大小](https://docs.apiseven.com/ai-gateway/reference/configuration-files.md#limit-request-body-size)。

下载媒体所花费的时间会计入请求的上游超时，从而减少服务提供方调用的可用时间。超时或连接失败可能触发重试，总共最多尝试三次。AISIX 不会重试 HTTP 错误状态或证书校验失败。

AISIX 最多并发获取一个请求中的八个 URL。同一请求中的重复 URL 只下载一次，不会跨请求缓存下载内容。

## 排查媒体下载问题[​](#排查媒体下载问题 "排查媒体下载问题的直接链接")

下载失败时，请求会以面向调用方路由的错误格式返回 `400`。错误消息会指出媒体内容及原因，但不包含 URL 查询字符串或片段。重定向失败时，错误消息会同时指出失败的重定向目标和原始 URL。

证书校验失败时，错误消息以以下内容结尾：

```
its TLS certificate could not be verified (see upstream.tls.ca_file)
```

地址被拒绝时，错误消息会指出主机以及允许访问的设置：

```
the gateway does not download the media URL <url>: its host is not a publicly routable address. To allow it, an operator adds <host> to outbound.ssrf_protection.allowed_hosts, or turns the check off with outbound.ssrf_protection.enabled: false
```

下载内容使请求超过合计限制时，`413` 消息会报告两部分的字节数：

```
the request body (277 bytes) plus downloaded media (168 bytes) exceeds the 400-byte request_body_limit_bytes limit
```

## 后续步骤[​](#后续步骤 "后续步骤的直接链接")

请根据客户端选择相应的请求契约：Chat Completions 客户端使用[兼容 OpenAI 的 Chat](https://docs.apiseven.com/ai-gateway/endpoints/openai-compatible-chat.md)，Anthropic 请求格式使用 [Anthropic Messages](https://docs.apiseven.com/ai-gateway/endpoints/anthropic-messages.md)，Responses 客户端使用 [Responses API](https://docs.apiseven.com/ai-gateway/endpoints/responses-api.md)。

向新的模型别名发送媒体前，请查看[服务提供方兼容性](https://docs.apiseven.com/ai-gateway/providers/compatibility.md)，确认服务提供方支持应用所需的端点和内容。如果 AISIX 必须从私有 HTTPS 主机下载媒体，请按上文所述将主机加入 SSRF 允许列表。如果该主机使用私有证书颁发机构，请按 [TLS 与 mTLS](https://docs.apiseven.com/ai-gateway/deployment/tls-and-mtls.md#trust-an-upstream-behind-a-private-certificate-authority)中的说明配置信任。
