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

画像生成と画像編集

対象:nexith-image · 非同期ジョブモデル(送信 → ポーリング/購読 → 成果物)

画像は同期 API ではありません。送信リクエストが行うのは 3 つだけです:パラメータの検証、レート制限、残高の予約とジョブ行の作成。 実際の生成は worker が非同期で実行します。完全な状態機械:

提交 202 → queued → running → completed
                          ↘ failed(重试耗尽)
        ↘ cancelled(客户端取消)

1. テキストからの画像生成#

curl -X POST https://api.nexith.ai/v1/images/generations \
  -H "Authorization: Bearer $NEXITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nexith-image",
    "prompt": "a cozy reading nook by the window, soft morning light",
    "size": "1024x1024"
  }'

レスポンス 202:

{"id": 123, "status": "pending", "idempotency_key": "…", "created_at": "2026-11-19T02:00:00Z"}

パラメータ:

フィールド 必須 説明
prompt はい プロンプト。空白のみは不可
model いいえ ホワイトリスト:nexith-image(デフォルト)。その他の値は 400
size いいえ 現在は固定 1024x1024
idempotency_key いいえ 冪等キー。同一ユーザーの重複送信は同じジョブを返し、二重課金しません

2. 画像編集(img2img)#

画像編集は 2 ステップです。まず参照画像をアップロードして安定した参照を取得し、次に画像編集ジョブを送信します。

2.1 参照画像のアップロード#

curl -X POST https://api.nexith.ai/v1/files \
  -H "Authorization: Bearer $NEXITH_JWT" \
  -F "file=@./reference.png" \
  -F "purpose=vision"
{"id":"nx-file://<uuid>","object":"file","bytes":812345,"filename":"reference.png","mime_type":"image/png","purpose":"vision"}

制限:≤10 MB。image/png、image/jpeg、image/webp、image/gif のみ(ファイルのマジックナンバーで検証)。

2.2 画像編集の送信#

curl -X POST https://api.nexith.ai/v1/images/edits \
  -H "Authorization: Bearer $NEXITH_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "把背景换成黄昏的海边",
    "image": "nx-file://<uuid>",
    "size": "1024x1024"
  }'
  • JWT のみ受け付けます:nx- API Key でこのエンドポイントを呼び出すと 403 を返します(chat サイト専用)。
  • image は現在のユーザー名下の nx-file:// 参照である必要があります。存在しない場合/権限外の場合は一律 400。
  • 画像編集と画像生成は同じ SKU、同じ価格、同じジョブフローです。

3. 結果の取得#

ポーリング#

curl https://api.nexith.ai/v1/jobs/123 \
  -H "Authorization: Bearer $NEXITH_API_KEY"
{
  "id": 123,
  "public_model": "nexith-image",
  "capability": "image.generate",
  "status": "completed",
  "attempt": 1,
  "error_message": null,
  "started_at": "2026-11-19T02:00:01Z",
  "completed_at": "2026-11-19T02:00:45Z",
  "created_at": "2026-11-19T02:00:00Z",
  "artifacts": ["https://nexith-artifacts-prod.s3.us-west-2.amazonaws.com/images/…"]
}
  • artifacts は署名付き URL で、有効期間は 7 日間です。期限切れ後は再生成するか、ご自身で別途保存してください。
  • error_message は対外的には固定の不透明文言で、アップストリームのモデル名/内部エラーは含みません。

イベント購読(推奨)#

curl -N https://api.nexith.ai/v1/jobs/123/events \
  -H "Authorization: Bearer $NEXITH_API_KEY"

フレーム形式はストリーミングプロトコル · ジョブイベントストリームを参照してください。クライアントが再接続すると イベント 0 からリプレイされ、イベントを取りこぼしません。

キャンセル#

curl -X POST https://api.nexith.ai/v1/jobs/123/cancel \
  -H "Authorization: Bearer $NEXITH_API_KEY"
# → {"id":123,"status":"cancelled"}

キャンセル後は予約額が全額返金されます。


4. 課金と冪等性#

テーマ 動作
予約 送信時に $0.10/枚でアトミックに予約。残高不足は 402 でキュー投入しない
精算 完了時に実際の金額で課金
返金 失敗、キャンセル、サーバー例外はいずれも自動で全額返金
冪等性 (user_id, idempotency_key) が一意。重複送信は元のジョブを返し、二重課金しない
レート制限 テキストと同じ (Key, モデル) のレート制限チェーン。超過時は 429 で資金はロックしない

5. プロンプトのヒント#

  • 画像モデルは具体的な名詞 + 構図 + 光 + スタイルに敏感です。抽象的な羅列は避けてください。
  • シリーズの一貫性が必要な場合は、確定した 1 枚を参照にして画像編集(img2img)する方が、テキストからの生成を繰り返すより安定します。
  • 文字のレンダリングは依然として失敗する可能性があります。正確な文字が必要な場合は、モデルに生成させるのではなく、後から重ねることを推奨します。