Fellowi APIで動画も生成: キー、モデル選択、最初のリクエスト

少し前までFellowi APIにできることは1つでした。テキストを入れると画像が出てくる。今はそれよりずっと多くのことができます。同じキーで動画クリップが作れ、画像にも動画にもモデルを選べ、API Consoleにはすべてのモデルが料金付きで並んでいるので、推測する必要はありません。プロダクトに画像や短い動きが必要で、そのためにGPUを自前で運用したくないなら、この記事はあなた向けです。

変わったこと

• 同じキーで動画。image-to-video、text-to-video、参照画像に基づくクリップを、画像と同じ残高、同じリクエストの形で。
• model フィールド。下書きには速くて安いモデル、最終版にはより強いモデル。画像では省略でき、以前の連携がずっと受け取ってきたものを同じ料金で受け取れます。動画のリクエストでは常にモデルを指定します。
• コードから読めるカタログ。GET /v1/api/modelsがキーで呼べるものと料金を返すので、古くなるリストを埋め込む代わりにアプリ側でモデル選択を作れます。
• 連携そのものの近道。コンソールの「Copy for ChatGPT/Claude」ボタンでリファレンス全体を一度にコピーできます。コーディングアシスタントに貼り付けて、使っている言語のクライアントを書かせてください。

キーを取得する

無料アカウントを作り、/api-consoleを開いて、キーに名前を付けて作成します。完全なキーが表示されるのは一度だけで、その後コンソールにはプレビューしか残らないので、すぐにシークレットストアにコピーしてください。すべてのリクエストはこれをbearerヘッダーで送ります。

Authorization: Bearer fk_live_your_key_here

環境ごと、プロダクトごとにキーを分けましょう。キーごとに1日のコイン上限を設定でき、ステージングのループのバグが一晩で残高を使い切るのを防ぐいちばん簡単な方法です。

最初の画像

生成は非同期です。キューに入れるとすぐに202が返り、画像は少し後に届きます。

POST /v1/api/images
Content-Type: application/json
Authorization: Bearer fk_live_your_key_here
Idempotency-Key: 7f1c2b90-order-4411

{
  "prompt": "a ceramic mug on a linen cloth, soft window light",
  "quality": "standard",
  "aspectRatio": "4:5"
}

Idempotency-Keyヘッダーは見た目以上に大切です。ネットワークは応答を落とすことがあり、このヘッダーがあれば同じ試行のリトライは二重に支払わず同じ生成を返します。自分の注文IDなどから、試行ごとに1つ作ってください。あとは完了までポーリングして結果をダウンロードします。

GET /v1/api/images/{id}          -> "queued" ... "succeeded"
GET /v1/api/images/{id}/content  -> the image bytes

quality、format、aspectRatio、有料のプロンプト改善はすべて任意で、どのデフォルトもそのオプションが生まれる前のAPIの動作です。imagesに参照画像のURLをいくつか渡すとリクエストは編集モデルで処理され、キャラクターや商品を画像間で同じ見た目に保てます。

モデルを選ぶ

GET /v1/api/models

キーで使える画像・動画モデルが、コイン料金と、動画なら最長クリップ、対応解像度、開始フレームの要否とともに返ります。使いたいものをmodelに渡してください。ユーザーが試している間は安いモデル、残すバージョンには強いモデル、という組み合わせがおすすめです。最新の数値は製品ページにもあり、課金するのと同じコードから読み込まれています。

最初のクリップ

image-to-videoは静止画から始まります。一度アップロードしてIDを保存します。

POST /v1/api/uploads
{ "imageBase64": "<your start frame, base64>" }

-> { "upload": { "id": "..." } }

そして画像と同じようにクリップをキューに入れます。

POST /v1/api/videos
Idempotency-Key: 7f1c2b90-clip-4411

{
  "model": "fellowi-image-to-video-turbo",
  "uploadId": "<id from /v1/api/uploads>",
  "prompt": "steam rises slowly from the mug, the camera drifts in",
  "durationSec": 5,
  "resolution": "720p",
  "generateAudio": false
}

GET /v1/api/videos/{id}をsucceededになるまでポーリングし、videoUrlをダウンロードします。クリップは秒単位ではなく分単位でかかるので、ゆっくりポーリングし、ユーザーにもそう伝えましょう。text-to-videoのモデルはアップロード自体が不要です。料金は選んだ解像度でのクリップ1秒あたりで、音声や追加の参照画像は対応モデルで上乗せされます。APIのクリップは常にコインで支払い、Directorプランの枠はWebの動画スタジオで作るクリップにのみ使われます。

実際のプロダクトに組み込む

• キーはサーバーに置く。ブラウザやモバイルアプリには絶対に渡さないでください。バックエンドが私たちを呼び、フロントエンドはバックエンドを呼びます。
• ジョブキューとして扱う。生成IDを自分のレコードと一緒に保存し、ワーカーからポーリングし、届いたらファイルの自前のコピーを保存します。私たちのコピーは配信用で、あなたのアーカイブではありません。
• 失敗も通常の結果として扱う。失敗した生成は自動でコインを返金し、TIMEOUT、MODERATION_REJECTED、VENDOR_ERROR、UNKNOWNのいずれかのコードを返します。それぞれに役立つ表示を用意し、再試行できるようにしてください。
• キーごとのレート制限を守る。これは割り当てではなく乱用対策で、コンソールの各キーの横に表示されます。本当の上限はコイン残高です。

料金と返金の仕組みはAPIがコイン建てである理由で、同じAPIの成人向けコンテンツについてはキャラクター生成APIガイドで詳しく書いています。

できないこと

Webhookはまだありません。ポーリングしてください。無料枠もありません。すべての呼び出しにスタジオと同じ料金でコインがかかります。モデレーションが拒否したものは生成されず、成人向けの出力はアプリが何であれ公開プラットフォームには向きません。また、規約は生成物の商用利用を制限していませんが、画像が唯一無二であることや第三者の権利から完全に自由であることは約束しません。自分で撮影していないストック画像と同じように扱ってください。それで作りたいものに合うなら、コンソールから始めましょう。