Skip to main content
本書では、HappyHorse Videos API の連携方法を紹介します。この API は統一された /happyhorse/videos エンドポイントと action パラメータにより、テキストからの動画生成、開始フレーム画像からの動画生成、参照画像からの動画生成、および動画編集をサポートします。

​
申請手順

HappyHorse Videos API を使用するには、まず Ace Data Cloud コンソール で API Token を取得し、控えておいてください。 まだログインまたは登録していない場合は、ログインページに自動的にリダイレクトされ、登録とログインが案内されます。完了後、自動的に現在のページへ戻ります。 1 つの API Token でプラットフォーム上のすべてのサービスを呼び出せるため、サービスごとに個別で申請する必要はありません。 初回申請時には無料クレジットが付与され、無料で体験できます。クレジットが不足した場合は、コンソール で共通残高をチャージできます。
📘 完全なドキュメント：HappyHorse Videos API →

​
操作タイプ

action は今回のリクエストの生成モードを決定します：
  • generate：テキストからの動画生成。デフォルトの action であり、happyhorse-1.0-t2v と happyhorse-1.1-t2v をサポートします。prompt の指定が必須です。
  • image_to_video：開始フレーム画像からの動画生成。happyhorse-1.0-i2v と happyhorse-1.1-i2v をサポートします。image_url の指定が必須です。
  • reference_to_video：参照画像からの動画生成。happyhorse-1.0-r2v と happyhorse-1.1-r2v をサポートします。prompt と 1～9 枚の image_urls の指定が必須です。
  • video_edit：動画編集。happyhorse-1.0-video-edit をサポートします。prompt と video_url の指定が必須で、0～5 枚の参照画像 image_urls を追加で指定できます。
各アクションはデフォルトで 1.1 モデルを使用します。video_edit は現在 happyhorse-1.0-video-edit のみです。

​
基本的な使用方法

テキストからの動画生成では prompt を指定するだけでよく、resolution、ratio、duration などのパラメータを指定することもできます：
返却結果の例は以下のとおりです：
フィールドの説明：
  • success：今回のリクエストが成功したかどうか。
  • task_id：Ace Data Cloud 側のタスク ID。タスク状態の照会に使用できます。
  • trace_id：今回のリクエストのトレース ID。問題の調査に使用します。
  • data：動画結果のリスト。
    • id：HappyHorse 側のタスク ID。
    • video_url：生成された動画の CDN リンクアドレス。
    • state：タスクの状態。pending / succeeded / error から選択できます。
    • duration：課金対象動画の長さ。単位は秒です。video_edit では入力動画と出力動画の長さの合計です。
    • resolution：出力解像度。
    • ratio：出力アスペクト比。
対応する CURL コードは以下のとおりです：
対応する Python コードは以下のとおりです：

​
開始フレーム画像からの動画生成

image_to_video を使用する場合、image_url は動画の開始フレームとして使用されます。出力アスペクト比は開始フレーム画像にできるだけ追従するため、このアクションでは ratio を指定する必要はありません。

​
参照画像からの動画生成

reference_to_video を使用する場合、image_urls には 1～9 枚の参照画像を指定できます。プロンプト内では、character1、character2 などを使用して対応する順番の画像を参照できます。

​
動画編集

video_edit を使用する場合、編集対象の動画 video_url と編集意図 prompt を指定する必要があります。任意の image_urls は、衣装変更、スタイル転送、または部分置換などの参照画像として使用されます。audio_setting には auto または origin を指定でき、origin は元の動画の音声を保持することを示します。

​
非同期コールバック

動画生成には一定の処理時間が必要です。長時間接続を維持して待機したくない場合は、callback_url を渡すことができます。この場合、API は直ちに task_id を返し、タスク完了後に最終結果をこのアドレスへ POST します：
直ちに返される結果は以下のとおりです：
ポーリングのみを希望し、コールバックが不要な場合は、"async": true を渡すこともできます。その後、HappyHorse Tasks API を通じてタスク結果を照会します。

​
課金説明

HappyHorse は出力動画の秒数と解像度に応じて課金されます：
  • 720P：約 $0.105 / 秒から。
  • 1080P：約 $0.18 / 秒から。
  • video_edit：入力動画と出力動画の合計時間に応じて課金されます。実際の課金時間は、タスク完了後の集計に基づきます。
失敗したタスクは課金されず、無料枠も消費しません。

​
エラー処理

リクエストに問題がある場合、API は対応するエラーコードと説明を返します。一般的なものは以下のとおりです：
  • 400：リクエストパラメータが不正です。たとえば action と model が一致しない、prompt / image_url / video_url が不足している、または duration が 3～15 秒の範囲を超えています。
  • 401：認証に失敗しました。token が無効であるか、API と一致していません。
  • 403：残高不足、またはプロンプトがコンテンツ審査に抵触して拒否されました。
  • 429：リクエストが頻繁すぎるため、レート制限が発動しました。しばらくしてから再試行してください。
  • 500：サーバー内部エラーまたは生成失敗です。