NNexithDocs
ステータスダッシュボード ↗
概要とクイックスタートモデルカタログガイドAPI リファレンス連携OAuth2 / OIDC

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 の期限切れによって無効になることはありません。