PixVerseをほかのAIやアプリとつなぐ（その1）：API、Webhook、CLIとスキル（Claude Code・Codexなど）を、公式の記述の範囲で手順にする

この記事は、公式の資料を2026年10月25日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。

手順は「公式のページに書かれている手順を、順に並べたもの」です。設定の例は、「公式の例の写し」か、「公式の記載に合わせて、この記事で組んだ例（動作は確かめていません）」のどちらかを、そのつど書き分けます。コマンドや設定の細かい書式は、要約を通して読んでいるため、全文は公式ページで確認してください。画面の表記は変わります。手元の画面と照らして読んでください。

先に結論

• AIエージェント（Claude Code、Codexなど）× PixVerse： 公式のCLIページとスキルのリポジトリが、CLIを入れ、スキルを入れる流れを案内しています。ログインは、人がブラウザで承認するデバイスフローです。エージェントごとの設定ファイルの書き方は、読んだ資料に書かれていませんでした。
• 自分のアプリ × PixVerse： APIとWebhookは、ドキュメントに具体的な書き方があります。ただし、キーを作る画面の操作順と、使える人の条件は、読んだドキュメントでは足りません。
• 権限の考え方： CLIとスキルは、ログインしたPixVerseのアカウントの権限で、クレジットを使います。
• ChatGPT／Codexのプラグイン、Canvas、他社モデル、MCPとSDK： 08（その2）を参照してください。

前提：用語をそろえる

• API：プログラムからPixVerseを呼ぶ方法です。
• APIキー：APIを使うための合言葉です。サーバー側で保管します。
• 非同期：注文を出すとすぐに受付番号が返り、結果はあとで取りに行く（または通知を受ける）形です。PixVerseのAPIは非同期です。
• Webhook：生成が終わったとき、PixVerse側から、登録したアドレスに通知を送る仕組みです。
• 署名（シグネチャ）：通知が本物かを確かめる印です。共有の秘密のキーで計算します。
• スキル：エージェントにCLIの使い方を教える手順書のまとまりです。
• プラグイン：ChatGPTなどの中から、外部のサービスを呼べるようにする追加の仕組みです。
• MCP：AIエージェントと外部の道具をつなぐ共通の仕組みです。
• デバイスフロー：端末では承認のためのアドレスを出し、承認は別のブラウザで行うログインの形です。
• ワークスペース：個人かチームかなど、使う作業の単位です。CLIの workspace コマンドで切り替えます。

連携の地図

連携1：API（自作のアプリ、他のAIサービスの裏側から呼ぶ）

1-1 使う前に

• キーを作る場所： 公式のQuick Startは「platform.pixverse.ai でサインインして、APIキーを作る」、FAQは「PixVerse API Platformのアカウント設定で作る」と書いています。ボタン名や押す順番は、読んだドキュメントには書かれていません。platform.pixverse.ai のページ自体は、取得では本文が読めませんでした。公式の開発者向けページは、キーの取り方を説明していない、と読めました。
• 使える人の条件： 03で読んだとおり、API向けの規約は提供相手を開発者に限る内容でした。
• ベースURL： https://app-api.pixverse.ai（本番、1つだけ）。地域やほかの環境の案内は、Start Hereのページに書かれていません。
• ヘッダー： API-KEY（必須）、Ai-trace-id（必須。リクエストごとに新しいUUID v4）、Content-Type（JSONなら application/json、アップロードなら multipart/form-data）。
• キーの置き場所： ヘッダーにだけ入れます。本文やクエリ文字列に入れません。サーバー側に置き、クライアントのコード、アドレス、スクリーンショット、公開ログに出さない、と公式が繰り返しています。クライアント側（ブラウザやアプリ）に出さない、という書き方です。
• 成功の判定： HTTP 200かつ ErrCode が0。HTTPが200でも ErrCode が0以外なら失敗です。

1-2 画像を渡す（公式のドキュメントの例）

画像から動画を作るときは、先に画像をアップロードします。

curl --location 'https://app-api.pixverse.ai/openapi/v2/image/upload' \
--header 'API-KEY: your-api-key' \
--header 'Ai-trace-id: 550e8400-e29b-41d4-a716-446655440000' \
--form 'image_url="https://example.com/image.png"'

• 画像ファイルを渡すときは、image_url の代わりに --form 'image=@"/path/to/file.png"' を使う、とドキュメントにあります。ファイルとURLは、どちらか一方だけです。
• 条件：JPEG、PNG、WebP。20MBまで。縦横とも10,000ピクセルまで。
• 応答の Resp.img_id が、あとで使うIDです。動画や音声用には、目次に「Upload Media (Video and Audio)」のページがあります。パスと応答のID名は、今回の確認では公式のページから読めておらず、公式で確認できていません。
• 注意： 返ったIDは、同じAPIアカウント、同じ地域でだけ使えます（Quick Startとエラーコードのページ）。

1-3 動画を作る（公式の例）

文章から（エンドポイントは POST https://app-api.pixverse.ai/openapi/v2/video/text/generate）：

curl --location 'https://app-api.pixverse.ai/openapi/v2/video/text/generate' \
--header 'API-KEY: your-api-key' \
--header 'Ai-trace-id: 550e8400-e29b-41d4-a716-446655440000' \
--header 'Content-Type: application/json' \
--data '{
    "model": "v6-max",
    "prompt": "A blue glass marble rolls across a clean white table",
    "duration": 1,
    "quality": "360p",
    "aspect_ratio": "1:1"
}'

画像から（POST https://app-api.pixverse.ai/openapi/v2/video/img/generate）の本文の例：

{
    "duration": 5,
    "img_id": 123456790,
    "model": "v6-max",
    "prompt": "Make the subject walk forward slowly.",
    "quality": "720p",
    "generate_audio_switch": false,
    "seed": 0
}

• どちらのページも、パラメータの表は空で、型や必須かどうかは書かれていません。上の例に出てくる名前だけが根拠です。ほかの値は、モデルの対応表（Model Capability Map）と料金表で確かめるよう、ページが案内しています。
• 応答の例：{"ErrCode": 0, "ErrMsg": "Success", "Resp": {"video_id": 123456789, "credits": 10}}。公式は「受け付けられたタスクの例。完了するまで確認する」と注記しています。この応答は、生成の完了ではありません。
• Resp.credits は、表示と暫定の突き合わせ用です。最終の記録は、アカウントの台帳（Billing）の引き落としと返金の記録、とドキュメントが書いています。
• ほかのエンドポイント：First and Last Frame、Reference-to-Video（Fusion）、Multi-Transition、Video Extend、Video Expand、Image Template Generation、Video Upscale、Video Restyle、Lipsync、Video Edit、Image Avatar、Sound Effect、Subject Replacement、Motion Control（Mimic）などがドキュメントの目次にあります（目次は公式のドキュメントのトップにあります）。

1-4 結果を取りに行く

GET /openapi/v2/video/result/{video_id} を、API-KEY と新しい Ai-trace-id を付けて呼びます。公式の記載に合わせて、この記事で組んだ例（動作は確かめていません）です。

curl --location 'https://app-api.pixverse.ai/openapi/v2/video/result/123456789' \
--header 'API-KEY: your-api-key' \
--header 'Ai-trace-id: （新しいUUID）'

1-5 渡るデータ、権限、外し方

1-6 うまくいかないときの確認点

• 同時実行の数は、プランと設定によると書かれ、数字は載っていません。API Consoleで現在の上限を見るよう、案内されています。
• 問い合わせ（api_business@pixverse.ai）には、エンドポイント、時刻、HTTPのステータス、ErrCode、ErrMsg、Ai-trace-id、video_id を添え、APIキーの全体は送らないよう、公式が書いています。
• 遅いからといって、同じ注文を重ねて出さない（status=5 の間は、元の video_id を問い合わせるかWebhookを待つ、と公式が書いています）。Ai-trace-id は追跡用として説明されており、重複防止の鍵とは書かれていません。

連携2：Webhook（完了の通知を自作のアプリで受ける）

ポーリング（繰り返しの問い合わせ）の代わりに、完了をWebhookで受ける方法です。公式のWebhook Callbacksのページの手順を並べます。

手順

1. PixVerse API Platformの「Webhook management」のページ（platform.pixverse.ai/webhook）で、HTTPSのコールバックのアドレスを登録します。登録すると、webhook_id と Secret Key（秘密のキー）が渡されます。管理画面の見た目は読めていません。
2. 動画を作るリクエストの本文に webhook_id を入れます。公式の例（Text-to-Videoの本文）は、aspect_ratio、duration、model、prompt、quality に加えて、"webhook_id": "1234" を入れる形でした。対応するエンドポイントは、Text-to-Video、Image-to-Video、First and Last Frame、Lipsync、Video Extend、Sound Effect、Reference-to-Video、Multi-Transition、Subject Replacement、Video Restyle、Motion Control、Video Edit、Video Upscaleです。
3. 完了すると、PixVerseがあなたのアドレスにPOSTを送ります。ヘッダーは Webhook-Timestamp（Unix秒）、Webhook-Nonce（32文字）、Webhook-Signature（HMAC-SHA256のBase64）、Ai-trace-id、Content-Type: application/json です。
4. 本文の例は、id、status、url、size、has_audio、credits のような項目です。項目は状態と機能によって変わる、と書かれています。届いたことは成功を意味しません。 status を、Query Task Statusの値と照らします。
5. 署名を確かめます。公式の手順の要点は次のとおりです（計算の細部は、公式ページの原文を見て実装してください）。
6. 署名の対象は、タイムスタンプ、nonce、エンコードした本文を、改行でつないだ文字列。
7. 本文は、各項目を key=value にし、キー名の昇順に並べ、& でつなぎ、URLエンコードする。
8. Secret KeyでHMAC-SHA256を計算し、Base64にして、Webhook-Signature と、時間の差が出ない比較（timing-safe）で突き合わせる。
9. 受け取ったら、HTTP 200と、本文が ok（文字列）だけの応答を返します。それ以外は失敗とみなされ、再送されます。

再送の間隔（公式の表）

2秒、10秒、30秒、1分、5分、15分、1時間、4時間の、全部で8回です。各間隔は最大で±10%ぶれます。最後の再送のあとは、失敗として扱われます。

公式が書くセキュリティの注意

• 業務の処理の前に、署名を確かめる。
• 古いタイムスタンプは受けない。公式は、たとえば約5分の範囲外、という例を挙げています（再生攻撃の対策）。
• HTTPSのアドレスを使う。
• Secret Keyを、クライアントのコードやバージョン管理に入れない。
• 重複して届くことがあるので、処理を重複に強くする。タスクIDと状態で重ねて数えない。

渡るデータ、外し方、確認点

連携3：CLI × AIエージェント（Claude Code、Codexなど）：スキルを入れる

公式のCLIページとスキルのリポジトリ（pixverseai/skills）が案内する、エージェント向けの道です。CLIのページは、対象として Claude Code、Codex、OpenCode、OpenClaw、Hermes などを挙げています。

手順（公式の記述を順に並べたもの）

1. CLIを入れる：npm install -g pixverse（Node.js 22.12以上）。入れ方は05を参照。
2. 人がログインする：pixverse auth login。SKILL.mdは、エージェントが実行する場合は pixverse auth login --json を使い、返ってきた承認用のアドレスを利用者に見せるよう、書いています（JSONモードはブラウザを開かないため）。承認は、利用者が自分のアカウントで行います。
3. スキルを入れる：

sh npx skills add https://github.com/pixverseai/skills --skill pixverse-ai-image-and-video-generator

1. エージェントに、PixVerseで作る依頼をします。READMEによると、エージェントは skills/SKILL.md を入口として読み、必要なときに個々の機能やワークフローのスキルだけを読み込みます。全部を一度に読み込まないよう、SKILL.mdが書いています。
2. エージェントは --json で出力を読み、create の結果のIDを控えます。

渡るデータ

権限（何ができてしまうか）

• スキルは、ログインしたあなたのPixVerseアカウントで、クレジットを使って生成します。アセットの削除（pixverse asset delete）、アップロード、フォルダの操作、ワークスペースの切り替え、Canvasの変更なども、同じログインでできるコマンドです。
• SKILL.mdは、「生成はアカウントのクレジットを使う」という趣旨の記述でした。使う前の確認の規則は、読んだ範囲では見つかりませんでした。「ユーザーが明示した制約（モデル、地域、ワークスペース、創作の条件）を優先する」「通常の生成の依頼で、プロンプトを黙って書き換えてよい、という許可にはならない」とも書かれています。
• 地域：PIXVERSE_REGION は --region より優先され、ログイン、ワークスペース、既定値は地域ごとに別です。

この記事の案（公式の手順ではありません）

エージェントに最初に渡す依頼の文を、公式の記述に合わせて組むなら、たとえば次のようにできます。動作は確かめていません。

PixVerseのスキルを使って、動画を1本作ってください。
・作る前に、使うモデル、画質、長さ、見積もりのクレジットを私に見せて、私が了承してから実行してください。
・ログインが必要になったら、承認のアドレスを私に見せてください。
・assetの削除、ワークスペースの切り替えはしないでください。

エージェント側の承認設定（コマンドの実行を都度確認するかなど）は、各エージェントの公式の資料で確認してください。

外し方

うまくいかないとき

• exit code 3（認証のエラー）→ pixverse auth status、pixverse auth login。
• exit code 4（クレジットまたは購読の上限）→ 購読とクレジットを確認。
• exit code 7（同時生成の上限）→ 実行中のタスクが終わるのを待つ。
• 古いCLIでは、モデルやフラグの対応を前提にできないので、必要な更新を知らせ、非対応の組み合わせで実行しない（SKILL.md）。
• タイムアウトは、送信の失敗を意味しない。むやみに再送せず pixverse task status で調べる（SKILL.md）。
• 一部のバッチが失敗しても、成功した出力は残し、終了コードが0以外でも使える結果が出ていることがある（SKILL.md）。

気をつけること

• この記事は、実際に使って確かめた記録ではありません。公式の資料を読んだ範囲です。
• 公式ページ同士で、CLIの使える条件の書き方が違います（「Free to use」と「購読者のみ」）。05を参照してください。
• API向けのドキュメントのパラメータ表は、取得では空のページが多く、例の本文に出てくる項目だけを書きました。値の範囲は、公式の対応表と料金表で確認してください。
• APIキー、WebhookのSecret Key、CLIのトークンは、共有しない、公開の場に貼らない。公式もキーについてそう書いています。
• スキルを通すと、エージェントの提供元の側にも、プロンプトや結果が渡ります。その扱いは、PixVerseの資料には書かれていません。
• 版は変わります。CLIの変更履歴の最新は1.4.13（2026-10-23）の表示でした。SKILL.mdは、CLI 1.4.2を想定した記述でした。
• 規約は変わります。この記事は法律の助言ではありません。

出典

• PixVerse CLI（PixVerse、確認日 2026-10-25）
• PixVerse CLI README（PixVerseAI／cli、GitHub、確認日 2026-10-25）
• PixVerse CLI Changelog（PixVerseAI／cli、GitHub、確認日 2026-10-25）
• pixverseai/skills（GitHub、確認日 2026-10-25）
• PixVerse CLI Skill（SKILL.md、pixverseai／skills、GitHub、確認日 2026-10-25）
• create-video（pixverseai／skills、GitHub、確認日 2026-10-25）
• PixVerse for Developers（PixVerse、確認日 2026-10-25）
• PixVerse API Platform ドキュメント（トップ・目次、確認日 2026-10-25）
• Quick Start（PixVerse API Platform ドキュメント、確認日 2026-10-25）
• Start Here（PixVerse API Platform ドキュメント、確認日 2026-10-25）
• Text-to-Video（PixVerse API Platform ドキュメント、確認日 2026-10-25）
• Image-to-Video and Video Templates（PixVerse API Platform ドキュメント、確認日 2026-10-25）
• Upload Image（PixVerse API Platform ドキュメント、確認日 2026-10-25）
• Query Task Status（PixVerse API Platform ドキュメント、確認日 2026-10-25）
• Webhook Callbacks（PixVerse API Platform ドキュメント、確認日 2026-10-25）
• Concurrency Rules（PixVerse API Platform ドキュメント、確認日 2026-10-25）
• Error Codes（PixVerse API Platform ドキュメント、確認日 2026-10-25）
• Get Account Balance（PixVerse API Platform ドキュメント、確認日 2026-10-25）
• Billing and Usage（PixVerse API Platform ドキュメント、確認日 2026-10-25）
• FAQ（PixVerse API Platform ドキュメント、確認日 2026-10-25）