ToAPIsToAPIs
用户文件

列出用户文件

分页查询当前账号已登记的自有文件

GET
/api/v1/user/file

国内用户请注意: 中国大陆用户请使用 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 | null

MIME 类型, 未知时为 null.

data.items[].size_bytesinteger | null

文件大小, 单位字节, 未知时为 null.

data.items[].created_atstring

文件创建时间, 不是登记时间.

data.items[].delete_statestring

none 未进入删除; 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.

通用鉴权, 限流和错误处理见接入方式.