reference_image_urlsarray<string>必須必須の配列で 1〜4 枚です。写真、イラスト、3D レンダリングを 1 人につき 1 枚使い、全身画像を推奨します。
- デフォルト値
- 指定なし
- 制約
- minItems:1maxItems:4
例は、選択中のエンドポイントの公開パラメーター定義から作っています。API キーとサンプル素材を差し替えて、ご自身のサーバーから送信してください。
SDK・連携https://api.spicyapi.ai/api/v1/jobs/createTaskAPI キーはサーバーの環境変数 SPICY_API_KEY に保存します。Bearer 認証を使用し、JSON リクエストには Content-Type: application/json を指定してください。
Authorization: Bearer $SPICY_API_KEY# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "comfyui/openjutsu-character-swap/video-edit",
"input": {
"reference_image_urls": [
"https://example.com/reference.png"
],
"resolution": "768p",
"video_url": "https://example.com/reference.mp4"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"このモデルの入力スキーマから生成した例です。API はどのリクエストも、同じスキーマで検証します。
これらのフィールドは、リクエスト本文の input オブジェクトに指定します。名前と型は API と一致します。デフォルト値の指定がない項目に、デフォルト値があると想定しないでください。
reference_image_urlsarray<string>必須必須の配列で 1〜4 枚です。写真、イラスト、3D レンダリングを 1 人につき 1 枚使い、全身画像を推奨します。
video_urlstring必須料金に影響必須の MP4 です。15 秒以内で切り返しがなく、対象者が最初のフレームに見える素材を指定します。
seedinteger任意任意の 0〜2147483647 の整数です。同じ乱数源で一度に一つの入力を変えて比較できますが、フレーム単位の一致は保証しません。
resolutionstring任意料金に影響480p、540p、768p、1080p から選びます。既定は 768p です。上位ほど秒単価が上がり、横長の実測値は 864×480、960×544、1376×768、1920×1056 です。
"480p""540p""768p""1080p"promptstring任意任意です。画像と同じ順に 1 行につき 1 人、外見や位置で対象を指定します。未指定なら 1 枚は主要人物、複数枚は登場順、同時なら左から右です。対象不明の画像は無視され、指定外の人物は残ります。
{
"additionalProperties": false,
"properties": {
"prompt": {
"description": "Optional. Who each picture replaces, one line per picture in the same order, such as \"the woman in black on the left\". Leave empty to replace people in order of appearance.",
"maxLength": 600,
"type": "string",
"x-ui": {
"order": 90,
"placeholder": "the rider in the blue shirt on the left\nthe rider in the red shirt on the right",
"rows": 3,
"widget": "textarea"
}
},
"reference_image_urls": {
"description": "One picture per person to replace, up to four. A full-body picture works best.",
"items": {
"contentMediaType": [
"image/jpeg",
"image/png",
"image/webp",
"image/gif"
],
"minLength": 1,
"type": "string"
},
"maxItems": 4,
"minItems": 1,
"type": "array",
"x-ui": {
"accept": [
"image/jpeg",
"image/png",
"image/webp"
],
"order": 95,
"primary": true,
"widget": "multi-upload"
}
},
"resolution": {
"default": "768p",
"description": "Output resolution. Sets the per-second rate.",
"enum": [
"480p",
"540p",
"768p",
"1080p"
],
"type": "string",
"x-ui": {
"affects_price": true,
"order": 60,
"widget": "radio"
}
},
"seed": {
"description": "Random seed for controlled comparisons, not a frame-identical guarantee.",
"maximum": 2147483647,
"minimum": 0,
"type": "integer",
"x-ui": {
"advanced": true,
"order": 10,
"widget": "number"
}
},
"video_url": {
"contentMediaType": [
"video/mp4",
"video/webm",
"video/quicktime"
],
"description": "Source clip, one continuous shot with the person you replace visible in the first frame. Up to 15 seconds; scene, motion and the original audio are kept.",
"minLength": 1,
"type": "string",
"x-ui": {
"accept": [
"video/mp4"
],
"affects_price": true,
"max_duration_seconds": 15,
"max_size_mb": 90,
"order": 100,
"primary": true,
"widget": "upload"
}
}
},
"required": [
"video_url",
"reference_image_urls"
],
"type": "object",
"x-pricing": {
"billingMode": "duration_capped",
"variantFields": [
"resolution"
]
}
}HTTP 202 はタスクを受け付けたという意味で、生成が終わったという意味ではありません。返ってきた taskId を保存し、そのタスクの状態を問い合わせてください。結果を待っている間に、同じ内容でタスクを作り直さないでください。
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3
{
"code": 200,
"msg": "success",
"request_id": "req_example_create",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"state": "queued",
"estimatedCost": "0.750000"
}
}受理レスポンスには今回の概算料金が含まれるため、アプリのタスク履歴と請求画面に同じ金額を表示できます。
curl --get "https://api.spicyapi.ai/api/v1/jobs/recordInfo" \
--data-urlencode "taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"ポーリングは約 2 秒間隔から始め、徐々に間隔を延ばします。終了状態になったら止めてください。通信が切れたときも、元の taskId で状態を確認します。作成をやり直すときは、同じ冪等キーと同じ本文をそのまま使い回してください。
import { verifyWebhook } from "@spicyapi/sdk";
// express.raw keeps the bytes we signed; express.json never matches.
app.post("/hooks/spicy", express.raw({ type: "application/json" }), (req, res) => {
const { payload } = verifyWebhook({
rawBody: req.body,
timestamp: req.header("X-Webhook-Timestamp"),
signature: req.header("X-Webhook-Signature"),
payloadVersion: Number(req.header("X-Webhook-Payload-Version")),
secret: process.env.SPICY_WEBHOOK_SECRET,
});
res.status(200).end();
void handleFinishedTask(payload);
});タスク作成時に callBackUrl を渡せば、完了したレコードが POST で届きます——ポーリングは一切不要です。配信には毎回 X-Webhook-Timestamp、X-Webhook-Signature、X-Webhook-Payload-Version が付きます。署名は taskId.timestamp.sha256(body) に対する HMAC-SHA256(base64)なので、生のバイト列で検証してください。JSON を解析して再度文字列化するとバイト列が変わり、検証は必ず失敗します。失敗した配信は再送されるため同じ taskId が二度届くことがあります。ハンドラーは冪等に。まず 2xx を返し、処理はその後で——応答が遅いと配信失敗として扱われます。
output を読むのは、state が succeeded のときだけにしてください。失敗したときは errorCode、errorMessage、request_id を手がかりに調べます。例に出ている料金や状態は、実際の請求ではありません。
{
"code": 200,
"msg": "success",
"request_id": "req_example_record",
"data": {
"taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
"model": "comfyui/openjutsu-character-swap/video-edit",
"state": "succeeded",
"output": {
"assets": [
{
"key": "tasks/2026/08/28/job_01k3m8x9q2z4v7n5p6r8s0t1w3/3f7a1c9e5b2d48f0a6c1e3d5b7f9a1c3.mp4",
"mime": "video/mp4",
"url": "https://example.r2.cloudflarestorage.com/results/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.mp4?X-Amz-Signature=SIGNATURE_FROM_RESPONSE",
"expiresAt": "2026-08-28T12:20:08.000Z"
}
]
},
"cost": "0.750000",
"settled": true,
"createdAt": "2026-08-28T12:00:00Z",
"completedAt": "2026-08-28T12:00:30Z"
}
}利用可能なファイルは assets[].url からそのまま開くか、ダウンロードできます。API の Authorization ヘッダーは不要です。署名付き URL は expiresAt で失効しますが、保存期間内であればタスクを再取得することで更新できます。処理中または利用できないファイルに URL はありません。署名付き URL は非公開情報として扱ってください。
アプリ、ターミナル、AI アシスタント、ビジュアルワークフローで SpicyAPI を活用。接続ガイドを選んでください。
上のコードを書く必要はありません。MCP サーバーを 1 回接続すれば、MCP に対応するエージェント(Claude Code、Codex、Cursor、Windsurf、VS Code、Gemini CLI、Cline、LibreChat)がこのモデルを名前で実行できます。シェルから 1 つのコマンドで実行することもできます。
Use comfyui/openjutsu-character-swap/video-edit to make a five-second shot of a neon-lit rooftop at dusk, slow push-in, and save it to ./out/.
エージェントは公開カタログからモデルを引き、ローカルファイルを代わりにアップロードし、正確な見積もりと上限額を示して確認を待ちます。承認するまで課金は発生しません。
claude mcp add spicyapi -e SPICY_API_KEY=$SPICY_API_KEY \
-- npx --yes --package=@spicyapi/mcp spicyapi-mcp
npx skills add spicyapi-ai/spicy-skill1 行目でツールを、2 行目で Skill を渡します。Skill は使い方の取り決めです——課金の前に見積もりを取り、ローカルファイルはバイト列を貼らずにアップロードし、完成した成果物の URL を推測せずに読む。ほかのクライアントも同じサーバーをそれぞれの設定ファイルから使います。開発者向けページをご覧ください。
npx @spicyapi/cli tasks create --model comfyui/openjutsu-character-swap/video-edit \
--input-json '{"reference_image_urls":["https://example.com/reference.png"],"resolution":"768p","video_url":"https://example.com/reference.mp4"}' \
--wait入力は上の例と同じ、このエンドポイント固有のスキーマに従います。--wait はタスクの完了までポーリングして結果を表示します。CI では --yes を追加すると確認を省略できます。先に SPICY_API_KEY を設定してください。API、CLI、MCP サーバーで同じキーを使えます。
npx @spicyapi/cli files upload ./poster.png
# -> spicy://uploads/01k3m8x9q2z4v7n5p6r8s0t1w3
npx @spicyapi/cli tasks create --model comfyui/openjutsu-character-swap/video-edit \
--input-json '{"video_url":"spicy://uploads/01k3m8x9q2z4v7n5p6r8s0t1w3"}' \
--waitリクエストが受け取るのは URL であってバイト列ではありません。先にアップロードし、出力される spicy:// URI を渡してください。上のフィールド名はこのエンドポイントのスキーマから取ったものです。MCP 経由のエージェントはこの手順を代わりに済ませます——前述の一文が ./poster.png をそのまま指せるのはそのためです。公開 HTTPS で参照できるメディアならアップロードは不要です。
npx @spicyapi/cli tasks create --model comfyui/openjutsu-character-swap/video-edit \
--input-json '{…}' --retention 1h --wait
npx @spicyapi/cli tasks get $TASK_ID # read back the retention that applied--retention は保持期間を短くするだけです——30m、1h、7d、あるいは 0 なら終了と同時に削除。実際に効くのはリクエスト・アカウント設定・プラットフォーム上限のうち最も短い値なので、指定した数値が通った前提で進めず、タスクレコードから読み戻してください。アカウントの許容より長い値を渡しても何も起きません。
ComfyUI Manager か下のコマンドで SpicyAPI ノードをインストールしたら、キャンバスで OpenJutsu Character Swap · Character Swap を検索してください。このノードにはこのページと同じオプションがあり、実行前に価格が表示されます。
cd ComfyUI/custom_nodes
git clone https://github.com/spicyapi-ai/comfyui-spicyapi埋め込みパネルはこのページと同じスキーマを参照するため、API 仕様とのずれを防げます。ドキュメント内の検索対象にする場合は、/api/embed/models/ の JSON を取得して描画してください。
<iframe src="https://spicyapi.ai/embed/ja/models/openjutsu-character-swap/api?model=comfyui%2Fopenjutsu-character-swap%2Fvideo-edit" width="100%" height="560" loading="lazy" title="リクエスト例" style="border:1px solid rgba(0,0,0,.12)"></iframe>