# 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[​](#understand-supported-media-paths "Direct link to 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[​](#control-which-urls-aisix-can-fetch "Direct link to 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[​](#forward-proxies-and-tls "Direct link to 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-media-fetching "Direct link to 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[​](#understand-download-limits "Direct link to 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](https://docs.api7.ai/ai-gateway/reference/configuration-files.md#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[​](#troubleshoot-media-downloads "Direct link to 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[​](#next-steps "Direct link to Next Steps")

Choose the request contract that matches your client: [OpenAI-Compatible Chat](https://docs.api7.ai/ai-gateway/endpoints/openai-compatible-chat.md) for Chat Completions, [Anthropic Messages](https://docs.api7.ai/ai-gateway/endpoints/anthropic-messages.md) for the Anthropic request shape, or the [Responses API](https://docs.api7.ai/ai-gateway/endpoints/responses-api.md) for Responses clients.

Before sending media to a new model alias, use [Provider Compatibility](https://docs.api7.ai/ai-gateway/providers/compatibility.md) 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](https://docs.api7.ai/ai-gateway/deployment/tls-and-mtls.md#trust-an-upstream-behind-a-private-certificate-authority).
