NNexithDocs
状态控制台 ↗
概览与快速开始模型目录指南API 参考集成OAuth2 / OIDC

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, 不会因为存储后端切换或预签名过期而失效。