3行でいうと

  • ブラウザの入口は app.lumalabs.ai。OSごとのインストール手順は、今回読んだ公式の資料には見つかりませんでした。スマホアプリの現状は、今回読んだ範囲では確認できていません（01を参照）。
  • APIの入口は https://agents.lumalabs.ai/v1。キーは platform.lumalabs.ai の開発者ダッシュボードで作る、と公式のFAQが書きます。キーは「luma-api-」で始まり、画面に出るのは1回だけです。
  • 公式のPython SDKは pip install luma-agents（Python 3.9以上）。キーは環境変数 LUMA_AGENTS_API_KEY に入れると、SDKが自動で読みます。TypeScript版とCLIの導入コマンドは、今回の取得結果には出ていませんでした。
  • APIには無料枠がなく、残高が足りないと依頼は受け付けられません（402）。アプリ側は、クレジットの使用量を管理する「Usage settings」があると公式の記事が書いています。
  • Claude から Luma を呼ぶプラグインや、Google Drive などの取り込みは、07にまとめました。APIの中身は、パラメータが08、ファイル・エラー・削除が09です。

この記事は、公式の資料を2026年10月25日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。手順は「公式の手順を順に並べたもの」で、画面の表記は公式ページの表記を写しています。手元の画面と照らして読んでください。この記事で組んだ例には、そのつど「動作は確かめていません」と書きます。

先に結論

前提：用語をそろえる

どの入口を使うか

入口 何をするか 入れるもの・要るもの この記事の節
Luma App（ブラウザ） ボードの上で、エージェントに頼む／ツールバーから自分で生成する ブラウザとLumaのアカウント A
Luma Agents API 自分のプログラムから画像・動画をつくる APIキー、残高、（あれば）公式SDK B
Claude から呼ぶ公式プラグイン Claude の会話の中から Luma を呼ぶ ClaudeとLumaのアカウント 07
Luma の中に外部の素材を取り込む Connectors Google Drive などから素材を読む Lumaのアカウントと各サービスのアカウント 07

A. Luma App（ブラウザ）に入って、最初の設定をする

A-1. OSごとの入手について

A-2. サインインして、最初の画面を見る（公式の記事の順）

  1. ブラウザで lumalabs.ai を開き、「Try Luma Now」か「Sign In」のリンクから app.lumalabs.ai に進みます。
  2. 公式の記事（Welcome To Luma Agents）が書く画面の部品は、次のとおりです。画面の名前は、この記事の名前に合わせて探してください。
部品 公式の記事の説明
Board 作業はすべてボードの上に整理される
Infinite canvas ボードの作業場。道具が置かれている
Agent chat つくりたいものを文章で書く場所
Agent 画像・動画・音声のモデルをまとめて動かし、制作を進める
Board UI 個別のモデルを手動で使いたいときの場所
Semantic search ボードの中の素材・参考資料・過去の版を探す
  1. 公式の記事は、順番をこう説明しています。サインインする、ボードで作業する、エージェントのチャットに、望む結果を自然な文章で書く。モデルの選び方まで細かく書く必要はなく、目的を書けばエージェントがプロンプトを組む、とあります。
  2. ツールバーの部品（ポインタ、画像生成、動画生成、音声生成、フレーム、図形、テキスト、付箋、色、メディアのアップロード）の使い方は、06に書きました。公式の記事は、ツールバーが画面のどこにあるかは書いていません。

A-3. 最初に決めておく設定

次の4つは、公式の記事が触れている設定や準備です。画面の道筋（どのメニューから行くか）は、読んだ範囲では書かれていないので、「確認できていない」と書きます。

設定 公式の記事に書かれていること 画面の道筋
使いすぎの歯止め 「Usage settings」のページに「On-Demand Spend」の切り替えがあり、含まれるクレジットを超えて使うときの上限（spending limit）を調整できる 公式で確認できていない
クレジットの仕組みの理解 月ごとの割り当てがあり、使い切れなかった分は請求期間の終わりに消える。失敗した生成のクレジットは自動で戻る。却下（reject）した出力は消費される 使用量を見る場所は、その記事に書かれていない
参照素材の置き場 公式の記事（How To Use References Properly）は、ロゴ、色、キャラクター、商品の参考画像などを、専用のフレームにまとめ、「Master Reference Assets」のように名前を付けておく方法を説明している。フレームの作り方は06 作り方はツールバー（06）
最初に伝える進め方 公式の記事（Stop Prompting, Start Directing）は、プロジェクトの最初に、質問してほしいこと、選択肢を出してほしいこと、あいまいなら止まって聞いてほしいこと、などを一度だけ伝える方法を挙げている チャットに書く（06）

A-4. 動作の確かめ方（アプリ）

公式の資料に、確認用の手順は書かれていません。この記事の案として、次の見方があります（案であり、公式の手順ではありません）。

  1. ボードを開き、エージェントのチャットに、短い依頼（06の「この記事の例」）を1つ書く。
  2. 返ってきた画像や動画が、ボードの上に並ぶか見る。
  3. 使用量の画面があれば、クレジットが減ったかを見る。減り方の画面の場所は、公式の記事で確認できていません。

B. Luma Agents API を使える状態にする

B-1. 全体の順番

  1. 開発者ダッシュボード（platform.lumalabs.ai）でアカウントを作り、APIキーを作る。
  2. 残高を用意する（無料枠はない）。
  3. キーを環境変数 LUMA_AGENTS_API_KEY に入れる。
  4. 公式のSDKを入れる（または curl で直接呼ぶ）。
  5. 最小の依頼を1つ出して、状態が「queued」で返ることを見る。

B-2. キーを作る（公式のFAQの記述）

公式のFAQ（docs.agents.lumalabs.ai/guides/faq）が書いていることです。ダッシュボード自体は今回読めていないため、ボタンの名前や並びは書けません。

  1. platform.lumalabs.ai でアカウントを作り、開発者ダッシュボードからキーを作る。
  2. キーは「luma-api-」で始まる。
  3. 生のキーが表示されるのは1回だけ。サーバーはハッシュしか保存しないので、なくした場合は、ダッシュボードで失効させて新しく作る。
  4. キーは複数作れる。「production」「staging」のように名前を付けると、追跡や、一部だけの失効に使える。
  5. 失効したキーは元に戻せない。
  6. 上限（分あたりの依頼数、同時に動かせるジョブ数）や残高は、キーごとではなく「クライアント」単位。同じクライアントのキーは、割り当てを共有し、お互いの生成を取得できる。分けたいときは、support に別のクライアントの用意を頼む、とある。

  7. キーには有効期限が付くことがあり、認証エラーの detail の文面で、未指定・無効・失効・期限切れが見分けられる。

  8. 他の資料との違い。 古い公式のMCP（lumalabs/luma-api-mcp）のREADMEは、キーの入手先を lumalabs.ai/api/keys と書いています。これは古い世代のモデル（photon、ray-2）用の説明で、現行のAPIの入手先は上のFAQの書き方です。ただし、そのREADMEに非推奨（deprecated）の表示は、今回の取得結果には見つかりませんでした。lumalabs.ai/api のページと、クイックスタートの概要ページは、キーの入手先を書いていません（03）。

B-3. 残高の用意と自動チャージ（公式のFAQ）

B-4. キーを環境変数に入れる

公式の資料は、環境変数の名前を LUMA_AGENTS_API_KEY、設定は export コマンド、と書いています。Windowsでの書き方は、今回読んだ資料には見つかりませんでした。

macOS／Linux（公式の記載に合わせた形。キーの実値は書かず、プレースホルダにしてあります）

export LUMA_AGENTS_API_KEY="luma-api-（ここに自分のキー）"

Windows（PowerShell）：この記事の案。公式の記載ではなく、動作は確かめていません

$env:LUMA_AGENTS_API_KEY = "luma-api-（ここに自分のキー）"

B-5. 公式SDKを入れる

言語 取得できた記述
Python pip install luma-agents。Python 3.9以上。非同期クライアントで aiohttp を使う場合は pip install luma-agents[aiohttp]。ライセンスは Apache-2.0（公式のGitHubのREADME）
TypeScript SDKがあることは公式のFAQとクイックスタートに書かれている。導入コマンドは、今回の取得結果に出ていなかった（公式のクイックスタートのタブで確認）
Go クイックスタートに、インポートのパスが github.com/lumalabs/luma-agents-go と出ている。導入コマンドは03に以前の記載がある
CLI 画像生成の例に --prompt の指定があることだけが読めた。導入の方法は、今回の取得結果に出ていなかった

Pythonの導入（公式READMEの記載）

pip install luma-agents

B-6. 最初の依頼を出す（動作の確かめ方）

Pythonの最小の例（公式READMEの例の写し。取得ページ上の表示で、細部は公式ページで確認してください）

import os
from luma_agents import Luma

client = Luma(
    auth_token=os.environ.get("LUMA_AGENTS_API_KEY"),  # This is the default and can be omitted
)

generation = client.generations.create(
    prompt="A glass of iced coffee on a marble countertop, morning light streaming through a window",
    aspect_ratio="16:9",
    model="uni-1",
)
print(generation.id)
  1. 上のコードを、キーを入れたターミナルで動かします。
  2. 期待される結果：生成のID（UUIDの形）が表示されます。公式の画像生成・動画生成のページによれば、依頼は非同期で、受け付けられるとHTTP 201が返り、直後の状態は queued です（クイックスタートの取得結果に出ていた状態は completed と failed だけで、ページによって書き方が違います）。
  3. 画像ができあがるのは、このあとです。状態が completed になると、output に署名つきのURLが入り、そのURLは1時間で期限切れになります。状態の聞き方は08に書きます。公式のFAQは、画像は通常30〜60秒かかる、と書いています。
  4. この例のモデル uni-1 は、画像の既定のモデルです（uni-1-max は高品質側）。

curlで状態を聞く（この記事で組んだ例。動作は確かめていません）

curl https://agents.lumalabs.ai/v1/generations/（生成のID） \
  -H "Authorization: Bearer $LUMA_AGENTS_API_KEY"

B-7. 返ってくる情報の見方

C. つまずきと確かめ方

症状 公式の資料が書く原因 確かめること
401（Pythonでは AuthenticationError） キーが未指定、形が違う、無効、失効、期限切れ。detail の文面は4種類ある（公式のエラーのページ） 環境変数が今のターミナルに入っているか。キーの前後に余計な文字がないか。ダッシュボードで失効していないか
402 残高が足りない。依頼は受け付けられていない ダッシュボードの残高と自動チャージ（B-3）
403 APIクライアントが停止または無効（生成の削除では、管理用の読み取りキーでも403） support に連絡（support+luma-agents-api@lumalabs.ai）
400 未知のモデル、モデルに合わない type、必要な source がない、比率が不正、プロンプトの長さが1〜6,000字の外、など 08のパラメータ表と照らす
413 入力の画像・動画が50 MBか1辺8,000 pxを超える、または埋め込みの動画が30秒を超える 縮小・圧縮、または公開URLかファイルAPIに切り替え
422 禁止の組み合わせ（style: "manga" と横長の比率など）、素材の読み込み失敗（base64の不正、URLに届かない） 組み合わせと素材のURL
429 detail が「Rate limit exceeded」なら分あたりの依頼数、「Too many concurrent jobs」なら同時ジョブ数 Retry-After の秒数を待つ（09の6）
状態が failed（content_moderated） プロンプトか入力画像が内容の基準に当たった。再送しても同じ プロンプトや参照を変える。公式のFAQは、実在の人物の名前や参照画像などで誤って引っかかることがあり、一般的な言い方に直すと変わることがある、と書く
出力のURLが開けない（403） 署名つきURLは1時間で期限切れ もう一度、状態を取得して新しいURLを得る
pip install が通らない READMEは Python 3.9以上を対象としている python --version で確認
アプリで画面が違う 公式の記事は日付が古い（2026年3〜6月）。モデルの名前やボタンは入れ替わる 手元の画面と、公式のラーニングセンターの新しい記事を照らす

気をつけること

出典