版本：1.7.1

媒体输入与 URL 获取

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

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

了解支持的媒体路径

AISIX 会为 Anthropic、Google Vertex AI，以及 Amazon Bedrock 的 InvokeModel 和 Converse 路径转换上游所支持的 image_url、input_audio 和 file 内容。在 Vertex AI 上，转换适用于 Claude 和 Gemini。跨区域 Grok 和 GPT 5.6 及更新模型默认使用 Bedrock Runtime 的兼容 OpenAI Chat Completions 路径；该路径保留 OpenAI 请求形态，只下载远程 image_url 并改写为 data: URL，不通过媒体获取转换 input_audio 或 file。需要 Converse 专属功能的请求仍会切换到 Converse。其他兼容 OpenAI 的适配器会按调用方发送的原样转发这些内容。

输入	AISIX 发送到上游的内容
内联数据，例如 `data:` URL、`input_audio` 或 `file.file_data`	服务提供方原生的内联媒体块。
发送到 Anthropic API 的 `https://` URL	原始 URL，因为 Anthropic 可以自行读取。
发送到 Gemini 的 `gs://` 或 `https://` URL，且调用方明确指定了媒体类型或 URL 扩展名指明了媒体类型	原始 URL，因为 Gemini 可以自行读取。
通过 Anthropic、Google Vertex AI，或 Amazon Bedrock InvokeModel/Converse 路径发送的其他任意 `http://` 或 `https://` URL	AISIX 下载内容并内联发送。这包括 Vertex AI 上的 Claude、发送到 Anthropic 或 Gemini 的 `http://` URL、Gemini 无法识别类型的 `https://` URL，以及通过 Bedrock InvokeModel/Converse 发送且模型支持的媒体。
通过 Bedrock Runtime 兼容 OpenAI Chat Completions 路径发送的远程媒体	AISIX 只下载 `image_url` 并将其改写为 `data:` URL；`input_audio` 和 `file` 保持 OpenAI 请求形态，不由媒体获取转换。
所选上游无法读取的 scheme，例如发送到 Bedrock 的 `gs://`	请求以 `400` 拒绝。

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

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

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

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

控制 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

除非 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。详见限制请求体大小。

下载媒体所花费的时间会计入请求的上游超时，从而减少服务提供方调用的可用时间。超时或连接失败可能触发重试，总共最多尝试三次。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，Anthropic 请求格式使用 Anthropic Messages，Responses 客户端使用 Responses API。

向新的模型别名发送媒体前，请查看服务提供方兼容性，确认服务提供方支持应用所需的端点和内容。如果 AISIX 必须从私有 HTTPS 主机下载媒体，请按上文所述将主机加入 SSRF 允许列表。如果该主机使用私有证书颁发机构，请按 TLS 与 mTLS中的说明配置信任。

了解支持的媒体路径​

控制 AISIX 可以获取的 URL​

正向代理与 TLS​

配置媒体获取​

了解下载限制​

排查媒体下载问题​

后续步骤​