通过 Files API 上传的每个文件默认都保存在私有存储中；获取它需要 API 密钥。公开 URL 可将已存储的文件转换为 SpaceXSI CDN 上的永久分享链接，任何人都能打开，无需 API 密钥。

创建后仍可完全控制：

随时撤销，只需一次 API 调用即可立即使 URL 失效。
自动失效，设置 expires_after（1 小时至 30 天），或让 URL 继承文件自身的过期时间，使二者同时失效。

创建公开 URL 不会修改底层私有文件，撤销 URL 也不会删除文件，两者的生命周期相互独立。

如果需要控制访问权限（例如仅限已登录用户），请将文件保持为私有，并通过自己的后端使用经过身份验证的 GET /v1/files/{file_id}/content endpoint 提供文件。

快速入门

# 1. Upload (or reference an existing) file
FILE_ID=$(curl -s https://api.x.ai/v1/files \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -F purpose=assistants \\
  -F file=@/path/to/diagram.png | jq -r '.id')

# 2. Create the public URL (empty JSON body uses defaults)
curl -s -X POST "https://api.x.ai/v1/files/$FILE_ID/public-url" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{}'
# {"public_url":"https://files-cdn.x.ai/<token>/file_abc123.png"}

# 3. When you're done sharing, revoke
curl -s -X POST "https://api.x.ai/v1/files/$FILE_ID/public-url/revoke" \\
  -H "Authorization: Bearer $XAI_API_KEY"

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))

# 1. Upload (or reference an existing) file
file = client.files.upload("/path/to/diagram.png")

# 2. Create the public URL
resp = client.files.create_public_url(file.id)

print(resp.public_url)
# https://files-cdn.x.ai/<token>/file_abc123.png

# 3. When you're done sharing, revoke it
client.files.revoke_public_url(file.id)

过期行为

创建公开 URL 时，可以选择通过 expires_after（单位为秒）设置过期时间。到期后，URL 会自动撤销，后续请求返回 404，无需再调用 API 清理。底层文件不受影响，仍可通过经过身份验证的 Files API 访问。

URL 的实际过期时间取决于两个因素：创建时是否传入 expires_after，以及底层文件是否有自己的过期时间。

文件没有过期时间，expires_after 被省略，URL 永不过期，直至你明确调用 revoke_public_url 或删除底层文件。
文件没有过期时间，expires_after 设置为 N，URL 会在 N 秒后自动撤销，文件本身不受影响。
文件在时间 T、expires_after 被省略，URL 会继承文件的过期时间，二者都在 T。
文件在时间 T、expires_after 设置为 N，URL 会在 N 秒后消失。N 必须小于或等于文件的剩余生命周期，否则请求会被拒绝。

expires_after 必须介于 3600 秒（1 小时） 与 2592000 秒（30 天） 之间。公开 URL 的存续时间绝不能超过文件；请求的 expires_after 大于文件剩余生命周期时会被拒绝。

# 1. Indefinite — file has no expiry.
# Must call POST /public-url/revoke to explicitly revoke.
curl -s -X POST "https://api.x.ai/v1/files/$FILE_ID/public-url" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -H "Content-Type: application/json" -d '{}'
# {"public_url":"..."} <- no expires_at field

# 2. URL-bound (24h)
curl -s -X POST "https://api.x.ai/v1/files/$FILE_ID/public-url" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"expires_after": 86400}'
# {"public_url":"...","expires_at":1755600000}

# 3. Inherited: upload with file expiration, then create with no expires_after
FILE_ID=$(curl -s https://api.x.ai/v1/files \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -F expires_after=7200 \\
  -F purpose=assistants \\
  -F file=@/path/to/photo.png | jq -r '.id')

curl -s -X POST "https://api.x.ai/v1/files/$FILE_ID/public-url" \\
  -H "Authorization: Bearer $XAI_API_KEY" \\
  -H "Content-Type: application/json" -d '{}'
# {"public_url":"...","expires_at":<matches file expiry>}

import os
from datetime import timedelta
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))
file = client.files.upload("/path/to/photo.png")

# 1. Indefinite: omit expires_after on a file with no expiry.
# Must call revoke_public_url to explicitly revoke the public URL.
resp = client.files.create_public_url(file.id)
assert not resp.HasField("expires_at")

# 2. URL-bound: pass expires_after as int seconds or a timedelta
resp = client.files.create_public_url(file.id, expires_after=timedelta(hours=24))
print(f"Expires at: {resp.expires_at.seconds}")

# 3. Inherited: file has its own expiration, omit expires_after on the URL
ttl_file = client.files.upload(
    b"\\x89PNG\\r\\n\\x1a\\n" + b"\\x00" * 32,
    filename="short-lived.png",
    expires_after=timedelta(hours=2),
)
resp = client.files.create_public_url(ttl_file.id)
# resp.expires_at matches the file's expires_at

幂等性

一个文件在同一时间最多只能有一个有效公开 URL。对已有有效 URL 的文件调用 create_public_url 会返回现有 URL，而不会生成新 URL，因此可安全地重复调用。

如果在后续调用中传入不同的 expires_after，现有 URL 的过期时间会原地更新，URL 中的 token 保持不变。

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))
file_id = "file_abc123"

# First call creates the URL
resp1 = client.files.create_public_url(file_id, expires_after=86400)  # 1 day

# Second call returns the same URL, no re-upload
resp2 = client.files.create_public_url(file_id, expires_after=86400)
assert resp1.public_url == resp2.public_url

# Calling again with a different expires_after extends/shortens the expiry
# while keeping the same URL
resp3 = client.files.create_public_url(file_id, expires_after=604800)  # 7 days
assert resp1.public_url == resp3.public_url
assert resp3.expires_at.seconds > resp1.expires_at.seconds

撤销公开 URL

撤销会使 URL 失效，并从文件元数据中清除该 URL。原始文件不受影响，仍可通过经过身份验证的 endpoint 访问。

curl -s -X POST "https://api.x.ai/v1/files/file_abc123/public-url/revoke" \\
  -H "Authorization: Bearer $XAI_API_KEY"
# {"id":"file_abc123","revoked":true,"public_url":"https://files-cdn.x.ai/..."}

# Calling again is safe — returns revoked=false
curl -s -X POST "https://api.x.ai/v1/files/file_abc123/public-url/revoke" \\
  -H "Authorization: Bearer $XAI_API_KEY"
# {"id":"file_abc123","revoked":false}

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))

# Revoke a public URL
resp = client.files.revoke_public_url("file_abc123")
print(f"Revoked: {resp.revoked}")    # True
print(f"Was URL: {resp.public_url}") # the URL that just stopped working

# The file itself is still available via authenticated endpoints
file = client.files.get("file_abc123")
print(file.filename)

# Revoke is idempotent and safe to call on:
# - files that never had a public URL (returns revoked=False)
# - files whose URL was already revoked (returns revoked=False)
# - files that have been deleted
client.files.revoke_public_url("file_abc123")  # no-op, no error

撤销是全有或全无的。一个文件同一时间只能有一个公开 URL，因此撤销会让所有持有该链接的人都无法访问。如果链接泄露给错误对象，唯一的补救方法是撤销并创建新 URL；新 URL 会使用全新的 token，旧 URL 将永久失效。

查找具有公开 URL 的文件

get_file 与 list_files 始终返回文件当前的公开 URL 状态。public_url 与 public_url_expires_at 会填充在每个具有有效公开 URL 的文件上。

还可以在 filter 上使用 list_files 参数，查找具有或不具有有效公开 URL 的文件：

# URL-encode the filter
curl -s "https://api.x.ai/v1/files?filter=public_url%20!%3D%20null" \\
  -H "Authorization: Bearer $XAI_API_KEY"

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))

# All files that currently have a public URL
with_url = client.files.list(filter="public_url != null")
for f in with_url.data:
    print(f.id, f.filename)

# All files that do not currently have a public URL
without_url = client.files.list(filter="public_url = null")

限制

最大文件大小：50 MiB。更大的文件仍可通过经过身份验证的 Files API 访问，但不能公开。
受限的内容类型。仅以下类型符合条件：
- image/png（.png）
- image/jpeg（.jpg、.jpeg）
- image/gif（.gif）
- image/webp（.webp）
- video/mp4（.mp4）
- video/webm（.webm）
- application/pdf（.pdf）
过期时间必须介于 1 小时和 30 天之间，且公开 URL 的存续时间绝不能超过文件。
删除文件会撤销公开 URL。文件被删除后（手动删除或到期），无法继续保留公开 URL。
每个文件同一时间只能有一个公开 URL。 create_public_url 具有幂等性，重复调用会返回同一 URL。撤销后，下一次 create_public_url 会签发新 token，之前分享的所有 URL 都将永久失效。
每个团队最多有 1,000 个有效公开 URL。创建新 URL 前，请撤销不再需要的 URL。

管理文件，上传、列出、获取和删除文件。
Imagine → Files API 集成，将已存储文件引用为 Imagine 输入、持久保存生成的资源，并在单个请求中创建公开 URL。
Files API 参考，完整的 REST endpoint 文档。

最后更新：2026 年 10 月 10 日

从写代码，到创作下一幕

Agent Plan & Coding Plan

Seedance 2.5

文件与集合

公开 URL

快速入门

过期行为

幂等性

撤销公开 URL

查找具有公开 URL 的文件

限制