列出用户文件
分页查询当前账号已登记的自有文件
国内用户请注意: 中国大陆用户请使用 https://api.toapis.cn 作为接口地址 (Base URL). 文档示例中的 https://api.toapis.com 请替换为 https://api.toapis.cn.
使用说明
按文件创建时间倒序列出当前账号已登记的自有文件, 同一时刻按 ID 倒序. 仅覆盖已登记文件, 不代表存储中所有历史对象. 响应不包含文件下载 URL, 存储路径或提示词; 关联任务可能稍后补齐.
本接口仅返回 data.items, data.next_cursor, 不返回 has_more, meta 或总数. 将非空 next_cursor 原样传入下一次查询的 cursor; 末页为 "", 空列表为 []. 游标绑定账号, 跨账号或篡改返回 400. 只支持 limit 和 cursor, 不支持时间或删除状态筛选.
鉴权
Authorizationstring请求头必填使用系统访问令牌, 格式为 Bearer YOUR_SYSTEM_ACCESS_TOKEN. 不接受模型 API Key, 无需 X-User-Id. 只操作当前认证账号自己的文件和策略, 不合并子账号数据.
请求参数
limitinteger查询默认值: 50每页条目数, 默认 50, 范围 1-100.
cursorstring查询上一页返回的非空 next_cursor. 首页省略, 末页为空字符串时停止翻页.
请求示例
curl --request GET \
--url 'https://api.toapis.com/api/v1/user/file?limit=50' \
--header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'import requests
response = requests.get(
"https://api.toapis.com/api/v1/user/file?limit=50",
headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
timeout=30,
)
response.raise_for_status()
print(response.json())const response = await fetch("https://api.toapis.com/api/v1/user/file?limit=50", {
method: "GET",
headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());响应字段
示例使用虚构数据. 通用响应格式见接入方式.
data.itemsobject[]本页文件, 空结果为 [].
data.items[].idstring文件 ID, 供单文件删除使用.
data.items[].sourcestring登记来源标识, 例如 task_result, upload, private_asset.
data.items[].task_kindstring | null可选关联任务类型, 例如 generation 或 export.
data.items[].task_idstring | null可选关联任务 ID, 尚未关联时为 null.
data.items[].mime_typestring | nullMIME 类型, 未知时为 null.
data.items[].size_bytesinteger | null文件大小, 单位字节, 未知时为 null.
data.items[].created_atstring文件创建时间, 不是登记时间.
data.items[].delete_statestringnone 未进入删除; pending 等待; deleting 执行中; blocked 被阻塞; deleted 仅用于历史遗留行. 列表不保留完整的文件删除历史.
data.next_cursorstring下一页游标, 末页为空字符串.
响应示例
{
"code": 0,
"message": "",
"data": {
"items": [
{
"id": "123",
"source": "task_result",
"task_kind": "generation",
"task_id": "task_example_01",
"mime_type": "image/png",
"size_bytes": 204800,
"created_at": "2026-11-01T08:00:00Z",
"delete_state": "none"
}
],
"next_cursor": ""
}
}错误处理
limit, cursor 或查询参数无效时返回 400; 文件读取暂时不可用时返回 503.
通用鉴权, 限流和错误处理见接入方式.