Files
POST /v1/files· Upload an image and get a stable reference
Uploads an image and returns an nx-file://<uuid> reference. That reference can be placed in a
conversation's image_url.url, or used as the image for /v1/images/edits — the gateway resolves
it on every request, with no reliance on presigned URLs and no expiry.
Request#
POST /v1/files
Authorization: Bearer nx-... # 或 chat JWT
Content-Type: multipart/form-data| Form field | Required | Description |
|---|---|---|
file |
✅ | Image file |
purpose |
— | Purpose tag; defaults to vision |
Limits#
| Item | Limit |
|---|---|
| Single file size | ≤ 10 MB |
| Type | PNG / JPEG / WebP / GIF (validated by file magic bytes; Content-Type is not trusted) |
| Request body | ≤ 10 MB (this route has its own body limit) |
Response#
{
"id": "nx-file://5f0c2f3a-8a0e-4c1e-9f0a-2b7c9d1e4a11",
"object": "file",
"bytes": 812345,
"filename": "reference.png",
"mime_type": "image/png",
"purpose": "vision"
}Using a reference#
Vision input in a conversation#
{
"role": "user",
"content": [
{"type": "text", "text": "描述这张图"},
{"type": "image_url", "image_url": {"url": "nx-file://5f0c2f3a-…"}}
]
}Image editing#
{
"prompt": "把背景换成海边",
"image": "nx-file://5f0c2f3a-…"
}A reference is valid only for the user who uploaded it; anyone else using it on any endpoint gets 400/404 (existence is not leaked).
Errors#
| Status | code | Scenario |
|---|---|---|
| 400 | invalid_request |
Missing file field / not multipart / unsupported type |
| 413 | payload_too_large |
File exceeds 10 MB |
Storage#
Files are stored in object storage (S3), isolated per user (uploads/<user_id>/…). References are
internal stable IDs that do not break when the storage backend changes or a presigned URL expires.