API ドキュメント

動画生成

POST /v1/video/generations

動画ジョブを送信し、すぐに task_id を返します。所要時間はモデル・長さ・解像度によりますが、おおむね 1〜5 分です。パスとレスポンスの形は new-api の動画チャネルに合わせてあるため、中継ゲートウェイからそのまま動画プロバイダーとして利用できます。

パラメータ

パラメータ型説明
promptstring必須。何を生成するか
modelstring/v1/models のモデル id。省略時は既定モデル
modestringtext=テキストから（既定）| image=画像から
durationinteger秒数。選んだ仕様の min_sec 〜 max_sec に丸められる
resolutionstring480p | 720p | 1080p | 4k。spec 指定時はそちらが優先
ratiostringadaptive | landscape | portrait | 16:9 | 9:16 | 4:3 | 3:4 | 1:1 | 21:9。省略した場合は width/height から向きを判定し、どちらも無ければ adaptive。これ以外の値はエラーになる。選んだモデルがどれに対応するかは /v1/models の aspect_ratios を参照
width / heightintegerピクセル指定。ratio が無いときだけ横長か縦長かの判定に使う。同値なら adaptive 扱い
specstring仕様キー。解像度と 1 秒あたりの価格を決める
imagestring開始フレームの URL。mode=image のときに使用
image_laststring終了フレームの URL。image と併用すると開始・終了フレーム指定になる
reference_imagesstring[]被写体の一貫性のための参照画像
reference_videosstring[]参照動画の公開 URL。reference_video_durations と同じ添字で対応
reference_video_durationsnumber[]各参照動画の長さ（秒）。検出可能な正数であること
reference_audiosstring[]参照音声の公開 URL。reference_audio_durations と同じ添字で対応
reference_audio_durationsnumber[]各参照音声の長さ（秒）。検出可能な正数であること
mode=image では image か reference_images のいずれかが必須で、両方空だとエラーです。参照動画と参照音声はモデルの対応能力に従います。選択した仕様で reference_media_max_sec>0 の場合、該当する各メディアに検出可能な正の長さが必要です。参照動画が秒単位課金の場合も reference_video_durations が必須です。非対応または上限超過の入力は明示的に拒否されます。n が 2 以上の場合も拒否します。動画は 1 本ごとに課金・レート制限するため、リクエストを分けて送信してください。

リクエスト例

bash
curl https://open.pikpikgo.com/v1/video/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "ゆっくり寄るカメラ、少女が振り返って微笑む",
    "mode": "text",
    "duration": 5,
    "resolution": "720p"
  }'

レスポンス例

json
{
  "task_id": "2608101915300490318827",
  "id": "2608101915300490318827",
  "object": "video",
  "model": "video-pro-1",
  "created_at": 1786000530,
  "status": "processing",
  "url": "",
  "format": "",
  "metadata": {
    "duration": 5,
    "resolution": "720p",
    "ratio": "adaptive"
  },
  "error": null,
  "credits": 60,
  "prompt": "ゆっくり寄るカメラ、少女が振り返って微笑む"
}

status が processing なら、ジョブはレンダラーに渡っています。返ってきた task_id で下記のエンドポイントをポーリングしてください。生成に失敗した場合、クレジットは自動的に返却されます。

動画タスクの取得

GET /v1/video/generations/{task_id} — 動画ジョブのポーリングはこちらで、/v1/tasks/{id} ではありません（あちらは画像専用です）。形は送信時のレスポンスと同じで、完了すると url が生成された動画、format がそのコンテナ形式になります。

bash
curl https://open.pikpikgo.com/v1/video/generations/2608101915300490318827 \
  -H "Authorization: Bearer $PIKPIK_API_KEY"
json
{
  "task_id": "2608101915300490318827",
  "id": "2608101915300490318827",
  "object": "video",
  "model": "video-pro-1",
  "created_at": 1786000530,
  "status": "succeeded",
  "url": "https://cdn.pikpikgo.com/video/2608101915300490318827.mp4",
  "format": "mp4",
  "metadata": {
    "duration": 5,
    "resolution": "720p",
    "ratio": "adaptive"
  },
  "error": null,
  "credits": 60,
  "prompt": "ゆっくり寄るカメラ、少女が振り返って微笑む"
}
error は成功時に空文字ではなく null です。失敗判定には status か error !== null を使ってください。タスクは作成したアカウントからのみ参照でき、他人のタスクと存在しないタスクは、まったく同じ 404 を返します。