3行でいうと

  • 大きな素材は、ファイルAPIで1回だけ上げ、file_id で参照できます。小さいファイルは multipart、大きいファイルは署名つきの3段で、5 GiBまでです。
  • 上限は、分あたりの依頼数と同時ジョブ数の2つです。超えると429で、待ち行列はなく、すぐに拒否されます。
  • 生成の削除は、いまのところSDKになく、HTTPで呼ぶと公式は書いています。削除の完了は、削除のタスクが completed になったときだけです。
  • 管理用のAdmin APIは、エンタープライズの管理者向けの読み取り専用です。LLM Inference は別の製品で、キーは営業を通じて発行されます。
  • AI同士をつなぐ場面の案は、11にまとめました。公式の事実ではなく、この記事の案です。

この記事は、公式の資料を2026年10月25日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。手順は「公式の手順を順に並べたもの」で、コード・コマンドは、公式の例を写したものと、この記事で組んだ例（動作は確かめていません）を、そのつど区別して書きます。実行の前に、公式ページの原文と見比べてください。

先に結論

前提：用語をそろえる

5. ファイルAPI：大きな素材を1回だけ上げる

公式のファイルのページの内容です。ファイルはAPIキーの範囲に属し、エンドユーザーごとのアクセス管理は自分で行う、とあります。

メソッド パス 用途
POST /v1/files アップロードの作成（小さいファイルは multipart、大きいファイルは署名つきJSON）
POST /v1/files/{file_id}/complete 署名つきアップロードの完了と取り込みの開始
GET /v1/files/{file_id} 1件のメタデータ
GET /v1/files?limit=&purpose=&cursor= 新しい順の一覧
DELETE /v1/files/{file_id} 論理削除（204）

5-1. 小さいファイル（公式の例の写し）

curl -X POST https://agents.lumalabs.ai/v1/files \
  -H "Authorization: Bearer $LUMA_AGENTS_API_KEY" \
  -F "file=@./reference.jpg" \
  -F "purpose=reference"

5-2. 大きいファイル（署名つき、3段）

  1. POST /v1/files に、filename、mime_type、size_bytes、purpose のJSONを送る。応答の upload に、url、method（PUT）、headers、expires_at が入る。
  2. upload.url に、返ってきたヘッダーのとおりに、宣言した大きさのファイルを PUT する。保存先に直接送るので、APIの依頼数の上限には数えられない。

  3. POST /v1/files/{file_id}/complete。バイトを上げる前に呼ぶと422。

  4. 署名つきは5 GiBまで。小さいファイルのサイズの上限は、ページに数字がありません（超えると413）。受け付ける画像・動画の形式の一覧も、ページに書かれていません。

5-3. 状態と使い方

6. 上限と再試行

レート制限のページの内容です。

項目 内容
RPM 60秒の窓での POST /v1/generations の数。画像・動画のすべての種類で1つの枠
同時ジョブ 提出から completed／failed までの数
評価の単位 APIクライアントごと。両方を通らないと429
429の見分け方 detail が「Rate limit exceeded」ならRPM、「Too many concurrent jobs」なら同時ジョブ
Retry-After 429に付く、待つ最小の秒数（1以上）。同時ジョブの429では60固定
ヘッダー X-RateLimit-Limit、-Remaining、-Reset（201とRPMの429に付く）。X-Request-Id、X-API-Version（すべて）
待ち行列 なし。すぐに拒否される
引き上げ 方法はページにない。上限は、プランに依存し、platform.lumalabs.ai に表示される、とある

7. 失敗の見分け方（エラーのページ）

種類 値 意味 再試行
同期（HTTP） 400、401、402、403、404、413、422 05のつまずき表を参照 変更が必要
同期 429、502、503 上限、取得の代理が使えない、素材の取り込みが使えない する
非同期の失敗 content_moderated プロンプトや入力画像が基準に当たった 変更が必要
非同期の失敗 generation_failed、output_not_found モデルの内部エラー、出力を取り出せない 同じ依頼を再送
非同期の失敗 budget_exhausted 途中で残高が尽きた 入金後
非同期の失敗 image_too_large、unsupported_format、corrupt_input、invalid_request 入力や依頼の問題 変更が必要
非同期の失敗 rate_limited 上流の提供元の制限 する

8. 生成と出力を消す（生成の削除のページ）

この記事で組んだ例（公式の例の生成IDを、変数 $GENERATION_ID に置き換えた形。動作は確かめていません）

curl -X DELETE https://agents.lumalabs.ai/v1/generations/$GENERATION_ID \
  -H "Authorization: Bearer $LUMA_AGENTS_API_KEY"

9. 管理用API（Admin API）

10. LLM Inference：別の製品

11. AIとAIをつなぐ：この記事の案

以下は、公式の資料からの事実ではなく、事実を組み合わせたこの記事の案です。

場面 案 根拠になる公式の記述
コードを書かせるAIに、APIの呼び出しを書かせる AIには、キーの実値を渡さず、環境変数 LUMA_AGENTS_API_KEY を読む形のコードを書かせる。ドキュメントのURL（クイックスタート、各パラメータのページ）と、この記事の表を渡す キーは環境変数に入れ、SDKが自動で読む（05）
生成の完了を待つ処理 状態の確認の間隔、上限の時間、署名つきURLの期限（1時間）を、コードに入れてもらう 08の1-4の表、署名つきURLは1時間
複数のAIやユーザーの依頼をまとめて流す user_id に、個人情報を含まない固定のIDを付ける。上限（RPMと同時ジョブ）で429を受けたときの再試行を入れる user_id（クイックスタート）、レート制限のページ
素材の受け渡し 大きな素材は、ファイルAPIで1回上げ、file_id で参照する ファイルのページ
社内のAI基盤から使量を見る Admin API の usage-breakdown を、分析のシステムに取り込む Admin APIのページ（対象は、エンタープライズの管理者）
OpenAI互換の道具から、別の言語モデルを呼ぶ LLM Inference の接続先とキー（営業を通じて発行）に差し替える LLM Inferenceのページ

12. 外し方のまとめ（API側）

対象 公式の資料に書かれていること
APIキー プラットフォームのダッシュボードで失効。失効したキーは元に戻せない（FAQ）。ダッシュボードの画面は今回読めていない
管理用の読み取りキー 失効の手順は、Admin APIのページに記載がない
ファイル DELETE /v1/files/{file_id}
生成と出力 DELETE /v1/generations/{id}（HTTP。SDKにはない）
データの書き出し FAQは、support に依頼する、と書く
自動チャージ ダッシュボードで設定（05のB-3）。止め方の画面は読めていない

気をつけること

出典