NNexithDocs
StatusDashboard ↗
Overview & quickstartModel catalogGuidesAPI referenceIntegrationsOAuth2 / OIDC

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.