跳到主要内容

文件

文件上传一次，之后用它的 id 引用：把图片或视频附在消息里，或把任何文件作为生成的输入。生成的结果也是文件。

上传​

以 multipart/form-data 发送文件，字段名为 file：

curl -s "$NEWEYES_API_BASE/v1/files" -X POST \
  -H "Authorization: Bearer $NEWEYES_USER_TOKEN" \
  -F "file=@living-room.jpg"
{
  "object": "file",
  "id": "3d0f…",
  "filename": "living-room.jpg",
  "size": 482113,
  "content_type": "image/jpeg",
  "created_at": "2026-10-19T08:05:00Z",
  "download_url": "https://…",
  "download_url_expires_at": "2026-10-19T09:05:00Z",
  "expires_at": "2026-11-18T08:05:00Z"
}
种类格式最大
图片JPEG、PNG、WebP10 MB
视频MP4、MOV50 MB
音频MP3、WAV、M4A、AAC25 MB
  • 文件类型按文件内容判断，而不是文件名或声明的类型。其他类型会被拒绝，返回 422 unsupported_media_type；超过上限的文件返回 413 file_too_large。
  • 上传有独立的速率限制，在请求限制之外另算：见限流。

读取文件​

GET /v1/files/{file_id} 返回文件和一个新的 download_url。下载链接每次读取时重新签发，有效一小时（到 download_url_expires_at 为止）；要新链接就再读一次文件。暂时无法生成链接时 download_url 为 null——稍后重试即可。

文件只对上传或生成它的终端用户可见。

文件保留多久​

  • 上传的文件在上传 30 天后过期（其 expires_at），除非在此之前被发送在消息里或被生成使用。过期后它无法再读取或使用（404 file_expired），内容也会被删除。
  • 在消息里发送过的文件随对话保留；被生成使用过的文件会保留；生成的结果也会保留。它们的 expires_at 为 null。

任务生成的媒体​

对话中任务生成的图片、视频、音频和文档不在这里列出：它们以 media.updated 帧出现在事件流上，并作为回复的 attachments 出现在会话的消息列表里，各自带着会过期的链接。