上传文件

上传文件用于发送消息时使用，支持图片、文档、音频和视频的多模态理解。上传的文件仅供当前终端用户使用。

POST /files/upload

上传文件

cURL

curl --request POST \
  --url https://{api_base_url}/files/upload \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file='@example-file' \
  --form 'user=<string>'

201

uploadSuccess

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "name": "product-photo.png",
  "size": 204800,
  "extension": "png",
  "mime_type": "image/png",
  "created_by": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "created_at": 1705407629,
  "preview_url": null,
  "source_url": null,
  "original_url": null,
  "user_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "tenant_id": "11223344-5566-7788-99aa-bbccddeeff00",
  "conversation_id": null,
  "file_key": "uploads/product-photo.png"
}

Authorizations

Authorization · string · header · required

API Key 认证。对于所有 API 请求，请在 Authorization HTTP 头中包含您的 API Key，并加上 Bearer 前缀。示例：Authorization: Bearer {API_KEY}。强烈建议将 API Key 存储在服务端，不要在客户端共享或存储，以避免 API Key 泄漏导致严重后果。

Body

multipart/form-data

文件上传请求。需要 multipart/form-data 格式。

file · file · required

要上传的文件。支持的类型包括图片、文档、音频和视频。

user · string · required

用户标识符，由开发者定义的规则生成，必须在应用内唯一。Service API 与 WebApp 的用户 ID 相互独立，即使取值相同也不指向同一用户。

Response

201

application/json

文件上传成功。

id · string<uuid>

唯一文件 ID。

name · string

文件名。

size · integer

文件大小（字节）。

extension · string | null

文件扩展名。

mime_type · string | null

文件的 MIME 类型。

created_by · string<uuid> | null

上传文件的用户 ID。

created_at · integer<int64>

上传时间戳（Unix 纪元秒）。

preview_url · string | null

文件的预览 URL。

source_url · string | null

文件的源 URL。

original_url · string | null

文件的原始 URL。

user_id · string<uuid> | null

关联的用户 ID。

tenant_id · string<uuid> | null

关联的租户 ID。

conversation_id · string<uuid> | null

关联的会话 ID。

file_key · string | null

文件的存储键。