画像生成と画像編集
対象:
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)する方が、テキストからの生成を繰り返すより安定します。
- 文字のレンダリングは依然として失敗する可能性があります。正確な文字が必要な場合は、モデルに生成させるのではなく、後から重ねることを推奨します。