文件 API

列出和管理与表单关联的文件上传。

文件 API 允许您列出与账户关联的文件上传。文件在受访者提交文件上传问题时创建，或在您在表单构建器中上传媒体（图片、视频）时创建。

所有响应体均使用 snake_case 字段命名。

Endpoints

GET/api/v1/files

列出文件

GET/api/v1/files

返回已认证用户的文件上传分页列表。包括构建器媒体上传（由用户拥有）和受访者文件上传（与用户的表单关联）。

查询参数

pageinteger

页码（默认：1）

per_pageinteger

每页结果数（默认：50）

响应字段

idstring

唯一的文件上传 ID

blob_urlstring

文件的公开访问 URL

original_namestring

用户上传时的原始文件名

uuid_namestring

在 Blob 存储中使用的 UUID 文件名

sizeinteger

文件大小（字节）

content_typestring

文件的 MIME 类型（例如 "image/png"、"application/pdf"）

form_idstring or null

此文件关联的表单（用于受访者上传）

user_idstring or null

上传此文件的用户（用于构建器媒体）。受访者上传时为 null。

created_atstring

ISO 8601 上传时间戳

文件类型

根据 user_id 和 form_id 字段，文件分为两类：

类别	`user_id`	`form_id`	说明
构建器媒体	已设置	null 或已设置	您在表单构建器中上传的图片、视频或文档（例如问题图片、Logo）
受访者上传	null	已设置	受访者通过文件上传问题提交的文件

存储限制

文件存储按账户计算。您可以通过用户 API 查看当前使用情况。存储限制因套餐等级而异。当表单被删除时，关联的受访者文件上传会被异步清理并回收存储空间。

响应

json

{
  "files": [
    {
      "id": "668a1b2c3d4e5f6a7b8c9d01",
      "blob_url": "https://abcdef.public.blob.vercel-storage.com/uploads/a1b2c3d4.pdf",
      "original_name": "project-proposal.pdf",
      "uuid_name": "a1b2c3d4.pdf",
      "size": 245760,
      "content_type": "application/pdf",
      "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "user_id": null,
      "created_at": "2026-02-25T14:30:00.000Z"
    },
    {
      "id": "668a1b2c3d4e5f6a7b8c9d02",
      "blob_url": "https://abcdef.public.blob.vercel-storage.com/uploads/e5f6a7b8.png",
      "original_name": "hero-banner.png",
      "uuid_name": "e5f6a7b8.png",
      "size": 1048576,
      "content_type": "image/png",
      "form_id": null,
      "user_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "created_at": "2026-02-20T10:15:00.000Z"
    }
  ],
  "total": 38,
  "page": 1,
  "per_page": 50
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/files?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

错误响应

此端点返回的标准错误响应。

错误码

401Unauthorized

缺少或无效的 API 密钥

500Server Error

服务器内部错误

错误示例

json

{
  "error": "Unauthorized"
}

最后更新：2026年4月6日