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