文件库

文件库统一展示当前账号可访问的源文件、任务结果和应用文件。每一项使用稳定的 file_id，并返回调用方当前可执行的能力。

翻译输入文档另提供 /api/v1/documents 列表、详情、更新和删除端点。document_id 用于创建处理任务；file_id 用于统一文件库权限与下载。不要假设两种 ID 可互换。

列表与详情

GET /api/v1/storage/files?offset=0&limit=50
GET /api/v1/storage/files/{file_id}

列表响应：

{
  "items": [
    {
      "id": "x7m4q2k9n6c1v8pa",
      "name": "report.docx",
      "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "size_bytes": 45678,
      "status": "ready",
      "publication_status": "draft",
      "origin": {
        "product_code": "omnidoc-main",
        "display_name": "OmniDoc"
      },
      "capabilities": {
        "can_view": true,
        "can_download": true,
        "can_update": true,
        "can_delete": true,
        "can_share": true
      },
      "created_at": "2026-10-01T12:00:00Z",
      "updated_at": "2026-10-01T12:00:00Z"
    }
  ],
  "has_more": true,
  "next_offset": 50
}

翻页时把 next_offset 作为下一次请求的 offset，has_more 为 false 时结束。

始终以每个条目的 capabilities 判断是否可下载、分享或授权给应用，不根据来源字段自行推断权限。

下载

GET  /api/v1/storage/files/{file_id}/content
POST /api/v1/storage/files/{file_id}/download-ticket

/content 会 302 跳转到短时有效的下载地址；跟随跳转时不要携带 API Key，推荐先申请 download-ticket。下载地址过期后重新申请，不要长期保存。

权限和链接

GET    /api/v1/storage/files/{file_id}/permissions
POST   /api/v1/storage/files/{file_id}/permissions
DELETE /api/v1/storage/files/{file_id}/permissions/{grant_id}

GET    /api/v1/storage/files/{file_id}/links
POST   /api/v1/storage/files/{file_id}/links
DELETE /api/v1/storage/files/{file_id}/links/{link_id}

权限变更与公开链接是不同能力。创建链接时明确设置受众、下载权限、过期时间和可选下载次数；不再需要时立即撤销。

工作区视图

GET /api/v1/workspace/files
GET /api/v1/workspace/entries
GET /api/v1/workspace/apps

工作区接口适合构建文件中心；/storage/files 适合围绕单个文件执行权限与下载操作。