Files
POST /v1/files· 画像をアップロードして安定した参照を取得
画像を 1 枚アップロードし、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 であり、
ストレージバックエンドの切り替えや署名付き URL の期限切れによって無効になることはありません。