Media Inputs and URL Fetching

AISIX carries image, audio, and file inputs from model requests into the format expected by the selected upstream. Inline data stays inline. A remote URL is either sent to an upstream that can read it or downloaded by the gateway and embedded in the provider-native request.

This behavior applies to /v1/chat/completions, to /v1/messages and /v1/responses requests that use chat translation, and to the native Claude Messages routes on Amazon Bedrock and Google Vertex AI. The selected provider and media type determine which path AISIX uses.

Understand Supported Media Paths

AISIX translates image_url, input_audio, and file parts for the Anthropic, Amazon Bedrock, and Google Vertex AI adapters. Bedrock translation applies to every model, through InvokeModel and Converse alike. On Vertex AI, it applies to Claude and Gemini. OpenAI-compatible adapters forward the parts as the caller sent them.

Input	What AISIX Sends Upstream
Inline data, such as a data: URL, input_audio, or file.file_data	The provider-native inline media block.
An https:// URL sent to the Anthropic API	The original URL, because Anthropic can read it.
A gs:// or https:// URL sent to Gemini, when the caller explicitly identifies the media type or the URL extension does	The original URL, because Gemini can read it.
Any other http:// or https:// URL sent through a native provider adapter	AISIX downloads the content and sends it inline. This includes every Bedrock model, Claude on Vertex AI, an http:// URL toward Anthropic or Gemini, and an https:// URL whose type Gemini cannot identify.
A scheme the selected upstream cannot read, such as gs:// toward Bedrock	The request is rejected with 400.

A part the upstream cannot accept is rejected with 400, naming its location as messages[i].content[j]; AISIX never silently drops it. For example, Claude models accept images and PDF documents but not audio.

For a downloaded URL, AISIX identifies the media type in this order:

1. The caller's format, mime_type, or content_type.
2. The response's Content-Type, unless it is application/octet-stream or binary/*.
3. The URL extension.
4. The downloaded content.

When none of these identifies a type, AISIX rejects the request with 400.

Control Which URLs AISIX Can Fetch

A media URL is supplied by the API caller, so gateway downloads use outbound.ssrf_protection. The protection is enabled by default. Unless allowed_hosts exempts the host, AISIX checks every address the host resolves to and every redirect hop, up to 10.

While protection is enabled, AISIX refuses loopback, private (RFC 1918), carrier-grade NAT, link-local, documentation and benchmarking, multicast, reserved, IPv6 unique-local, and IPv6 link-local addresses. This includes the 169.254.169.254 metadata endpoint. A direct connection uses only addresses that AISIX checked.

List a host in outbound.ssrf_protection.allowed_hosts when AISIX should reach it despite its address, or set outbound.ssrf_protection.enabled to false to turn off the check.

A transparent proxy or fake-IP DNS service can resolve a public host into 198.18.0.0/15, which AISIX treats as a benchmarking range. Add the media hosts to allowed_hosts in that environment, or turn off the protection.

Forward Proxies and TLS

Media downloads use HTTPS_PROXY, HTTP_PROXY, or ALL_PROXY unless NO_PROXY covers the host. While SSRF protection is enabled and the host is not allowlisted, AISIX resolves and checks it before handing the request to the proxy. A host that the gateway cannot resolve is therefore refused even when the proxy could reach it. Add the host to allowed_hosts, or turn off the protection, when the gateway cannot resolve it locally.

Downloads trust the certificate authorities in upstream.tls.ca_file and honor upstream.tls.verify. They never present the upstream client certificate, and they do not forward the caller's headers.

Configure Media Fetching

Configure downloads in the gateway's startup configuration:

config.yaml (media URL downloads)

upstream:
  media_fetch:
    enabled: true
    max_bytes: 52428800
outbound:
  ssrf_protection:
    enabled: true
    allowed_hosts: ["media.internal", "10.0.0.5:9000"]

❶ Media fetching is enabled by default. Set this field to false to reject a URL that the selected upstream cannot read with 400.

❷ The download limit applies to each URL and defaults to 50 MiB.

❸ SSRF protection is enabled by default. Set this field to false to turn off address checks and ignore the allowlist.

❹ Each allowlist entry is a host, which allows any port, or host:port. Write an IPv6 address with a port as [addr]:port. An invalid entry stops the gateway at startup.

To set the address controls through environment variables, use AISIX_OUTBOUND__SSRF_PROTECTION__ENABLED and AISIX_OUTBOUND__SSRF_PROTECTION__ALLOWED_HOSTS. Write the list as a comma-separated value:

AISIX_OUTBOUND__SSRF_PROTECTION__ALLOWED_HOSTS="media.internal,10.0.0.5:9000"

A JSON array is not accepted in the environment variable and stops the gateway at startup.

The SSRF setting governs only URLs supplied by API callers, which currently means media downloads. It does not check operator-configured URLs such as a provider key's api_base, guardrail, MCP, A2A, JWKS, or exporter endpoint.

Understand Download Limits

Each media URL is limited to upstream.media_fetch.max_bytes. All downloads in one request also count, together with the inbound body, against proxy.request_body_limit_bytes. Crossing the per-URL limit returns 400; crossing the combined request limit returns 413. See Limit Request Body Size.

The time spent downloading media counts against the request's upstream timeout, reducing the time available for the provider call. A timeout or connection failure can trigger retries, for up to three attempts in total. AISIX does not retry an HTTP error status or a certificate-verification failure.

AISIX fetches up to eight URLs from one request concurrently. A repeated URL is downloaded once within that request. Downloads are not cached across requests.

Troubleshoot Media Downloads

A failed download returns 400 in the caller-facing route's error format. The message names the media part and the reason without including the URL query string or fragment. When a redirect fails, it names both the failed redirect target and the original URL.

A certificate failure ends with:

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

A refused address identifies the host and the settings that allow it:

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

When downloaded content crosses the combined request limit, the 413 message reports both byte counts:

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

Next Steps

Choose the request contract that matches your client: OpenAI-Compatible Chat for Chat Completions, Anthropic Messages for the Anthropic request shape, or the Responses API for Responses clients.

Before sending media to a new model alias, use Provider Compatibility to confirm that the provider supports the endpoint and content your application needs. If AISIX must download media from a private HTTPS host, add the host to the SSRF allowlist described above. When that host uses a private certificate authority, configure trust as described in TLS and mTLS.