中文文档
API Console

文件与集合

公开 URL

查看 Markdown
创建 API Key 了解 Grok 4.7

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

创建后仍可完全控制：

  • 随时撤销，只需一次 API 调用即可立即使 URL 失效。

  • 自动失效，设置 expires_after（1 小时至 30 天），或让 URL 继承文件自身的过期时间，使二者同时失效。

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

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

快速入门

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 大于文件剩余生命周期时会被拒绝。

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 保持不变。

Python

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 访问。

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 的文件：

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。

最后更新：2026 年 9 月 9 日