Repository Public
1<!-- source: https://docs.x.ai/developers/files/public-urls (from https://docs.x.ai/llms-full.txt, retrieved 2026-09-19T05:28:55Z) -->2#### Files & Collections34# Public URLs56Every file you upload through the [Files API](/developers/files/managing-files) lives in private storage by default — fetching it requires your API key. **Public URLs** turn a stored file into a permanent, shareable link on the xAI CDN that anyone can open — no API key required.78You stay in control after creation:910* **Revoke at any time** with a single API call to immediately invalidate the URL.11* **Auto-expire** by setting `expires_after` (1 hour up to 30 days), or let the URL **inherit the file's own expiry** so both vanish together.1213Creating a public URL doesn't modify the underlying private file, and revoking it doesn't delete the file — the two lifecycles are independent.1415If you need to gate access (e.g. only logged-in users), keep the file private and serve it through your own backend using the authenticated [`GET /v1/files/{file_id}/content`](/developers/files/managing-files#getting-file-content) endpoint instead.1617> [!TIP]18>19> Generating images or videos with the [Imagine API](/developers/model-capabilities/imagine)? You20> can create a public URL **in the same request that produces the asset** via21> `storage_options.public_url`. See [Imagine → Files API22> Integration](/developers/model-capabilities/imagine/files).2324## Quick Start2526```pythonXAI27import os28from xai_sdk import Client2930client = Client(api_key=os.getenv("XAI_API_KEY"))3132# 1. Upload (or reference an existing) file33file = client.files.upload("/path/to/diagram.png")3435# 2. Create the public URL36resp = client.files.create_public_url(file.id)3738print(resp.public_url)39# https://files-cdn.x.ai/<token>/file_abc123.png4041# 3. When you're done sharing, revoke it42client.files.revoke_public_url(file.id)43```4445```bash46# 1. Upload (or reference an existing) file47FILE_ID=$(curl -s https://api.x.ai/v1/files \\48 -H "Authorization: Bearer $XAI_API_KEY" \\49 -F purpose=assistants \\50 -F file=@/path/to/diagram.png | jq -r '.id')5152# 2. Create the public URL (empty JSON body uses defaults)53curl -s -X POST "https://api.x.ai/v1/files/$FILE_ID/public-url" \\54 -H "Authorization: Bearer $XAI_API_KEY" \\55 -H "Content-Type: application/json" \\56 -d '{}'57# {"public_url":"https://files-cdn.x.ai/<token>/file_abc123.png"}5859# 3. When you're done sharing, revoke60curl -s -X POST "https://api.x.ai/v1/files/$FILE_ID/public-url/revoke" \\61 -H "Authorization: Bearer $XAI_API_KEY"62```6364> [!WARNING]65>66> Public URLs can only be created for files that **already exist** in your Files API storage. You67> cannot create a public URL during upload — upload the file first, then call `create_public_url`68> (or use `storage_options.public_url` on an Imagine request).6970## Expiry Behaviour7172You can optionally set an expiry on a public URL at creation time via `expires_after` (in seconds). Once the deadline passes, the URL is automatically revoked — subsequent requests return `404` and you don't need to make a follow-up API call to clean it up. The underlying file is unaffected and remains available through the authenticated Files API.7374The URL's effective expiry comes from two inputs: whether you pass `expires_after` at creation, and whether the underlying file [has its own expiration](/developers/files/managing-files#upload-with-expiration-ttl).7576* **File has no expiration, `expires_after` omitted** — URL never expires. It lives until you explicitly call `revoke_public_url` or delete the underlying file.77* **File has no expiration, `expires_after` set to `N`** — URL auto-revokes `N` seconds from now. The file itself is untouched.78* **File has its own expiration at time `T`, `expires_after` omitted** — URL inherits the file's expiry. Both disappear at `T`.79* **File has its own expiration at time `T`, `expires_after` set to `N`** — URL auto-revokes `N` seconds from now. `N` must be ≤ the file's remaining lifetime, otherwise the request is rejected.8081`expires_after` must be between **3600 seconds (1 hour)** and **2592000 seconds (30 days)**. A public URL can never outlive its file — requesting an `expires_after` greater than the file's remaining lifetime is rejected.8283```pythonXAI84import os85from datetime import timedelta86from xai_sdk import Client8788client = Client(api_key=os.getenv("XAI_API_KEY"))89file = client.files.upload("/path/to/photo.png")9091# 1. Indefinite: omit expires_after on a file with no expiry.92# Must call revoke_public_url to explicitly revoke the public URL.93resp = client.files.create_public_url(file.id)94assert not resp.HasField("expires_at")9596# 2. URL-bound: pass expires_after as int seconds or a timedelta97resp = client.files.create_public_url(file.id, expires_after=timedelta(hours=24))98print(f"Expires at: {resp.expires_at.seconds}")99100# 3. Inherited: file has its own expiration, omit expires_after on the URL101ttl_file = client.files.upload(102 b"\\x89PNG\\r\\n\\x1a\\n" + b"\\x00" * 32,103 filename="short-lived.png",104 expires_after=timedelta(hours=2),105)106resp = client.files.create_public_url(ttl_file.id)107# resp.expires_at matches the file's expires_at108```109110```bash111# 1. Indefinite — file has no expiry.112# Must call POST /public-url/revoke to explicitly revoke.113curl -s -X POST "https://api.x.ai/v1/files/$FILE_ID/public-url" \\114 -H "Authorization: Bearer $XAI_API_KEY" \\115 -H "Content-Type: application/json" -d '{}'116# {"public_url":"..."} <- no expires_at field117118# 2. URL-bound (24h)119curl -s -X POST "https://api.x.ai/v1/files/$FILE_ID/public-url" \\120 -H "Authorization: Bearer $XAI_API_KEY" \\121 -H "Content-Type: application/json" \\122 -d '{"expires_after": 86400}'123# {"public_url":"...","expires_at":1755600000}124125# 3. Inherited: upload with file expiration, then create with no expires_after126FILE_ID=$(curl -s https://api.x.ai/v1/files \\127 -H "Authorization: Bearer $XAI_API_KEY" \\128 -F expires_after=7200 \\129 -F purpose=assistants \\130 -F file=@/path/to/photo.png | jq -r '.id')131132curl -s -X POST "https://api.x.ai/v1/files/$FILE_ID/public-url" \\133 -H "Authorization: Bearer $XAI_API_KEY" \\134 -H "Content-Type: application/json" -d '{}'135# {"public_url":"...","expires_at":<matches file expiry>}136```137138## Idempotency139140A file can have **at most one active public URL at a time**. Calling `create_public_url` on a file that already has one returns the existing URL without producing a new one — it's safe to call repeatedly.141142If you pass a different `expires_after` on a subsequent call, the existing URL's expiry is updated in place. The token in the URL stays the same.143144```pythonXAI145import os146from xai_sdk import Client147148client = Client(api_key=os.getenv("XAI_API_KEY"))149file_id = "file_abc123"150151# First call creates the URL152resp1 = client.files.create_public_url(file_id, expires_after=86400) # 1 day153154# Second call returns the same URL, no re-upload155resp2 = client.files.create_public_url(file_id, expires_after=86400)156assert resp1.public_url == resp2.public_url157158# Calling again with a different expires_after extends/shortens the expiry159# while keeping the same URL160resp3 = client.files.create_public_url(file_id, expires_after=604800) # 7 days161assert resp1.public_url == resp3.public_url162assert resp3.expires_at.seconds > resp1.expires_at.seconds163```164165## Revoking a Public URL166167Revoking invalidates the URL and clears it from the file's metadata. The original file is untouched and continues to be accessible through authenticated endpoints.168169```pythonXAI170import os171from xai_sdk import Client172173client = Client(api_key=os.getenv("XAI_API_KEY"))174175# Revoke a public URL176resp = client.files.revoke_public_url("file_abc123")177print(f"Revoked: {resp.revoked}") # True178print(f"Was URL: {resp.public_url}") # the URL that just stopped working179180# The file itself is still available via authenticated endpoints181file = client.files.get("file_abc123")182print(file.filename)183184# Revoke is idempotent and safe to call on:185# - files that never had a public URL (returns revoked=False)186# - files whose URL was already revoked (returns revoked=False)187# - files that have been deleted188client.files.revoke_public_url("file_abc123") # no-op, no error189```190191```bash192curl -s -X POST "https://api.x.ai/v1/files/file_abc123/public-url/revoke" \\193 -H "Authorization: Bearer $XAI_API_KEY"194# {"id":"file_abc123","revoked":true,"public_url":"https://files-cdn.x.ai/..."}195196# Calling again is safe — returns revoked=false197curl -s -X POST "https://api.x.ai/v1/files/file_abc123/public-url/revoke" \\198 -H "Authorization: Bearer $XAI_API_KEY"199# {"id":"file_abc123","revoked":false}200```201202**Revocation is all-or-nothing.** A file can only have one public URL at a time, so revoking breaks the link for everyone who has it. If a link leaks to the wrong party, the only remedy is to revoke and create a new URL — the new one will have a fresh token and the old URL stays permanently dead.203204## Finding Files with a Public URL205206`get_file` and `list_files` always return the current public URL state of a file. `public_url` and `public_url_expires_at` are populated on every file with an active public URL.207208You can also use the [`filter`](/developers/rest-api-reference/files/manage) parameter on `list_files` to find files with or without an active public URL:209210```pythonXAI211import os212from xai_sdk import Client213214client = Client(api_key=os.getenv("XAI_API_KEY"))215216# All files that currently have a public URL217with_url = client.files.list(filter="public_url != null")218for f in with_url.data:219 print(f.id, f.filename)220221# All files that do not currently have a public URL222without_url = client.files.list(filter="public_url = null")223```224225```bash226# URL-encode the filter227curl -s "https://api.x.ai/v1/files?filter=public_url%20!%3D%20null" \\228 -H "Authorization: Bearer $XAI_API_KEY"229```230231## Limitations232233* **Maximum file size: 50 MiB.** Larger files remain available through the authenticated Files API but cannot be made public.234* **Restricted content types.** Only the following are eligible:235 * `image/png` (`.png`)236 * `image/jpeg` (`.jpg`, `.jpeg`)237 * `image/gif` (`.gif`)238 * `image/webp` (`.webp`)239 * `video/mp4` (`.mp4`)240 * `video/webm` (`.webm`)241 * `application/pdf` (`.pdf`)242* **Expiry must be between 1 hour and 30 days**, and a public URL can never outlive its file.243* **Deleting the file revokes the public URL** automatically. You cannot keep a public URL alive after the file is deleted (manually or by expiration).244* **One public URL per file at a time.** `create_public_url` is idempotent and returns the same URL on repeat calls. After a revoke, the next `create_public_url` issues a new token — any previously shared URL becomes permanently invalid.245* **Up to 1,000 active public URLs per team.** Revoke URLs you no longer need before creating new ones.246247## Related248249* [Managing Files](/developers/files/managing-files) — Upload, list, retrieve, and delete files.250* [Imagine → Files API Integration](/developers/model-capabilities/imagine/files) — Reference stored files as Imagine inputs, persist generated assets, and create public URLs in a single request.251* [Files API Reference](/developers/rest-api-reference/files) — Full REST endpoint documentation.252