Files
POST /v1/files· 上传图片并获得稳定引用
上传一张图片,返回 nx-file://<uuid> 引用。该引用可以放进对话的 image_url.url,
也可以作为 /v1/images/edits 的 image——由网关在每次请求时解析,不依赖预签名
URL,不会过期。
请求#
POST /v1/files
Authorization: Bearer nx-... # 或 chat JWT
Content-Type: multipart/form-data| 表单字段 | 必填 | 说明 |
|---|---|---|
file |
✅ | 图片文件 |
purpose |
— | 用途标签,默认 vision |
限制#
| 项目 | 限制 |
|---|---|
| 单文件大小 | ≤ 10 MB |
| 类型 | PNG / JPEG / WebP / GIF(按文件魔数校验,不信 Content-Type) |
| 请求体 | ≤ 10 MB(本路由独立 body limit) |
响应#
{
"id": "nx-file://5f0c2f3a-8a0e-4c1e-9f0a-2b7c9d1e4a11",
"object": "file",
"bytes": 812345,
"filename": "reference.png",
"mime_type": "image/png",
"purpose": "vision"
}使用引用#
对话视觉输入#
{
"role": "user",
"content": [
{"type": "text", "text": "描述这张图"},
{"type": "image_url", "image_url": {"url": "nx-file://5f0c2f3a-…"}}
]
}改图#
{
"prompt": "把背景换成海边",
"image": "nx-file://5f0c2f3a-…"
}引用只对上传它的用户有效;他人在任何端点上使用都会得到 400/404(不泄漏存在性)。
错误#
| 状态 | code | 场景 |
|---|---|---|
| 400 | invalid_request |
缺 file 字段 / 不是 multipart / 类型不支持 |
| 413 | payload_too_large |
文件超过 10 MB |
存储#
文件存放在对象存储(S3),按用户隔离(uploads/<user_id>/…)。引用是内部的稳定 ID,
不会因为存储后端切换或预签名过期而失效。