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이므로 스토리지 백엔드가 바뀌거나 프리사인드가 만료되어도 무효화되지 않습니다.