https://gateway.ngrok.ai/v1/files.
The request and response shapes match the provider’s own API, so the OpenAI and Anthropic SDKs work with one extra header.
Endpoints
Name the provider
A file request has no model, so the gateway can’t work out the provider on its own. Every Files API request must send theNgrok-AIG-Provider header:
The gateway removes this header before it calls the provider.
Other providers, including Google, aren’t supported.
The access key’s configuration must allow the provider.
Upload and use a file
Upload the file, then reference its ID in a request to a model from the same provider. A file ID only means something to the provider that stored it./v1.
The gateway adds the files-api-2025-04-14 beta flag to Anthropic file requests for you, and keeps any other beta flags you send.
Pass Ngrok-AIG-Provider on each file call rather than as a client default header, since inference requests don’t need it.
Files work in these request types:
Paying with credits or your own key
The gateway picks credentials for a file request the same way it does for a model request to that provider: from the routing rule in the access key’s configuration. If the access key has no configuration, or the configuration has no rule for that provider, the gateway uses your stored provider key when you have one, and credits otherwise. Each request uses one credential and doesn’t switch partway. A file stored with your own key lives in your provider account, and a file uploaded with credits lives with ngrok.ai, so they’re never mixed. Upload files and send the requests that use them with the same access key, so both go through the same credentials. To be sure, add a routing rule for the provider to the access key’s configuration.With your own provider key
Requests go straight through to your provider account:- Listing returns every file in your provider account, including files you uploaded outside the gateway.
- You can reference any file your provider account holds.
- Expiry, retention, and storage limits are the provider’s own.
When you pay with credits
ngrok.ai stores the file under an ngrok.ai account at the provider and keeps track of which files belong to your account:- Expiry: Files expire 72 hours after upload. On OpenAI, any
expires_afteryou send is replaced with that 72-hour expiry. - Storage limit: Your account can hold up to 5 GB of files per provider. Delete files you no longer need to free up room. Expired files stop counting once they’re removed, shortly after they expire.
- Listing: Listing only returns files your account uploaded with credits. Pages hold at most 100 files. Follow the cursor in the response (
afterfor OpenAI,after_idfor Anthropic) to read the rest. OpenAI’sorder=ascand Anthropic’sbefore_idaren’t supported. - Using files: A request can only reference files your account uploaded with credits. If a request references any other file ID, the gateway won’t use credits for that model. It uses your own provider key for that provider if one is routed, and otherwise returns
ERR_NGROK_27240.
Limits
- File size: An upload can be at most 512 MiB, whichever credentials it uses.
- Timeout: A transfer must finish within your account’s total timeout, 120 seconds by default. Raise it in Account Settings for large files on slow connections.
- Credits: Uploads, listings, metadata, and downloads need a positive credit balance, but they don’t spend credits. Deletes work at a zero balance, so you can always free storage.
Errors
File errors use the provider’s error format, so your SDK raises its usual exception. A request that doesn’t name a provider gets the OpenAI format.
See Error codes for every gateway error.
Next steps
- Pay with credits: Call providers without your own provider keys
- Bring your own provider key: Use files stored in your provider account
- Access key configurations: Control which credentials a request uses