3行でいうと

  • この記事の連携は、すべてAPIキーがあって成り立ちます。キーは、API用のクレジットを買ってから作ります。Webアプリのトークンとは別です。キーは、人に見せないものです。
  • 結果は、「こちらから取りに行く（polling）」か「Webhookで通知を受ける」で受け取ります。公式のAPIのFAQは、画像生成ではwebhookの設定が「best practice」だと書いています。
  • 渡るデータは、プロンプト、入力画像、設定です。公式のAPIのページは、入力画像は非公開で学習に使わない、public をfalseにした生成も学習に使わない、と書いています。
  • 外すときの要になるのは、キーを消すことです。API Accessのタブでキーを消せる、とAPIのFAQは書いています。
  • BlueprintsのAPIは、開発者向けドキュメントとヘルプで書き方が違います。併記します。

この記事は、公式の資料を2026年10月25日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。

手順は、公式の手順を順に並べたものです。設定例は、「公式の例の写し」か、「公式の記載に合わせて、この記事で組んだ例（動作は確かめていません）」のどちらかに、そのつど分けて書きます。公式ページは要約の形で取得したため、設定ファイルやコードの中身が原文と違う可能性があります。使う前に、公式ページの原文を見てください。画面の表記は変わるので、手元の画面と照らして読んでください。

先に結論

前提：用語をそろえる

この記事（その1）で扱うつなぎ方

つなぎ方 相手 認証 公式の手順の有無 この記事の節
REST API 自分のコード、他のソフト APIキー（authorization: Bearer） Quick Startにあり 1
Webhook 自分のサーバー callback用のキー（authorization: Bearerで送られる） あり 2
Get API Code 自分のコード Production APIアカウント あり 3
Blueprints（API） 自分のコード APIキー あり（Blueprints Guide） 4
Python SDK／TypeScript SDK Python、Node.jsなど bearer_auth／bearerAuth READMEにあり 5

MCP（Cursorなど）、Edit in Canva、Make.com、Pabbly Connectは、08です。

1. REST APIで呼び出す（Quick Startの順）

設定する画面と書く内容

  1. 画面：https://app.leonardo.ai/api-access（または、Webアプリの左メニューの「API Access」）。05のEの手順で、API用のクレジットを買い、「Create New Key」でキーを作ります。
  2. 呼び出す側（あなたのコードやコマンド）：キーを authorization: Bearer <YOUR_API_KEY> として送ります。accept と content-type は application/json です。
  3. 呼び出しの例は、05のEに載せたQuick Startのcurl（POST https://cloud.leonardo.ai/api/rest/v1/generations）です。生成が実行されるので、API用のクレジットが使われます。

結果の取り方

公式の資料にある、取り方は次のとおりです。

方法 公式の記述
polling（こちらから取りに行く） 生成の応答には generationId が含まれる。GET https://cloud.leonardo.ai/api/rest/v1/generations/<generationId> を呼ぶと、画像のアドレスが generations_by_pk.generated_images[].url に入る（Blueprints Guideの最後の手順に載っている形）。まだ終わっていないと、generated_images が空で、状態が PENDING。COMPLETE か FAILED になるまで確かめる（APIのFAQ）
webhook（通知で受ける） 次の節。APIのFAQは、画像生成ではwebhookの設定が「best practice」だと書いている（Webhookのガイド自体には、「recommended」の語は無い）

渡るデータ

権限と上限

項目 公式の記述
キーの権限の範囲 Production APIキーは、すべてのエンドポイントで使える（旧いUser APIキーは非推奨）
キーの数 1アカウントにつき10個まで
同時に動かせる数 Pay as you goで「Up to 10 concurrent generations」。上げたいときはカスタムプラン（APIのページ）。細かい決まりの「Guide to Concurrency, Queue and Rate Limit」のページは、サイトが機械の取得を許可せず、読めていません
課金 Webアプリの購読とは別。ドル建てのAPI Credit。期限はなし
費用の見積もり WebFAQは、アプリのPricing Calculatorか、そのAPIのエンドポイントで見積もれる、と書いている

外し方

目的 公式の記述
1つのキーを使えなくする 使わないキーは、API Accessのタブで消す（APIのFAQ）。「消すと、そのキーが無効になる」と明記したページは、読んだ範囲では見つからなかった
webhookの設定を変える・外す 変更するには、新しいProductionキーを、新しい設定で作り、そちらに切り替えて、旧いキーを消す（Webhookのガイド）
APIのアカウントごと 別々には消せない。Webのアカウントを消すと、APIのアカウントも削除の予定になり、データは戻らない（APIのFAQ）

うまくいかないとき

05のつまずき表と、公式のエラー一覧（API Error Messages）を見ます。代表的な対応です。

表示・症状 原因（公式の記述） 直し方
Invalid response from authorization hook／Authentication hook unauthorized this request キーの形が不正、または間違い キーが正しいか、authorization: Bearer <キー> の形かを見る
200なのに画像の配列が空 生成が終わっていない 状態がCOMPLETEかを見る。またはwebhook
400 Too many images num_images が上限を超えた 減らす、または分ける
403 content moderation filter 審査に引っかかった プロンプトを直す
<MODEL_ID> is not supported within the Production API そのモデルが、Production APIにない 別のモデルIDを使う
モデルのIDが分からない 公式のFAQ：List Platform Modelsのエンドポイント、またはGet API Code、またはWebアプリの「Finetune Models」→「Platform Models」→「View More」で調べる 同左
自分で訓練したモデルのID Webアプリの「Finetune Models」→「Your Models」→「View More」（FAQ） 同左

2. Webhook（生成の完了通知）を受ける

公式ドキュメント「Guide to the Webhook Callback Feature」が書く範囲です。

設定する画面

  1. Production APIキーを作る流れ（API Accessの「Create New Key」）の中に、webhookのコールバックURLと、webhookのコールバック用のAPIキーを入れる欄があります。どちらも、キーを作るために必須ではありません。
  2. コールバックURLは、HTTPSでなければなりません。httpのURLを入れると、「Key Creation Error Occurred」になる、とAPIのエラー一覧は書いています。
  3. 設定を変えるには、新しい設定で新しいキーを作り、切り替えてから、旧いキーを消します。
  4. メニューの正確な場所やボタンの表記は、このガイドでは書かれていません。手元の画面と照らしてください。

渡るデータ（Leonardoからあなたのサーバーへ）

{
  "type": "image_generation.complete",
  "object": "generation",
  "timestamp": 1699490546932,
  "api_version": "v1",
  "data": {
    "object": {
      "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "status": "COMPLETE",
      "images": [
        {
          "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
          "url": "https://cdn.leonardo.ai/...",
          "generationId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
        }
      ]
    }
  }
}

通信を許可する送信元（ガイドが挙げる6つのIPアドレス）

35.173.108.170
34.239.69.60
52.73.75.186
3.229.99.26
44.218.0.197
174.129.230.221

アドレスは変わる可能性があります。使う前に公式ページで最新を確認してください。

うまくいかないとき（ガイドの確認点）

確認すること 内容
ヘッダー 受け側が、authorization: Bearer を受け付けるか
ファイアウォール IPアドレス、場所、ヘッダーで、通信を止めていないか。上の6つのアドレスを許可する
証明書 SSL証明書の連鎖（中間証明書を含む）が正しいか。ガイドは、確認のコマンドとして openssl s_client -showcerts -connect YOUR_DOMAIN:443 -servername YOUR_DOMAIN を挙げている
URL HTTPSか

3. Get API Code：Webで作った設定から、コードを出す

公式ドキュメント「Guide to Get API Code」が書く手順です。

手順

  1. Webアプリで、画像か動画を作ります。モデルを選び、設定が合うまで調整します。
  2. 生成が終わったら、その作品の3点のメニュー（⋯）を押します。
  3. 「Get API Code」を選びます。
  4. 表示の中で、言語を選びます（cURL、Python、Node.js）。
  5. コピーのボタンで、コードをコピーします。生成の設定と、正しいAPIのエンドポイントが入っています。
  6. コードを自分のプロジェクトに貼り、YOUR_API_KEY を、自分のProduction APIキーに置き換えます。

条件と注意

4. BlueprintsをAPIから実行する

公式ドキュメント「Blueprints Guide」が書く手順です。公式の資料の間に、書き方の違いがあります。

資料 書かれていること
開発者向けドキュメント「Blueprints Guide」 APIに対応しているBlueprintを、APIから実行できる。自分でBlueprintを作る機能は「Coming Soon」（03で読んだ内容）。
ヘルプ「Blueprints by Leonardo.Ai」 APIでの利用は今後の予定（「Soon, you'll be able to ... access them through the Leonardo API」の趣旨）。自分のBlueprintの作成、共有、APIでの組み込みも、今後の予定

どちらが現在の状態かは、公式の資料では確認できていません。Blueprints Guideの手順は、次のとおりです（要約経由で取得）。

手順（Blueprints Guideの順番）

どのリクエストも、authorization: Bearer <YOUR_API_KEY> を付けます。

  1. （任意）Blueprintの一覧：GET https://cloud.leonardo.ai/api/rest/v1/blueprints。ガイドの例は、first（件数、例は10）と platforms: ["API"]（APIに対応するものだけ）を渡しています。一覧の応答の形は、ガイドには載っていません。
  2. （任意）詳細を見る：GET https://cloud.leonardo.ai/api/rest/v1/blueprints/<BlueprintのID>
  3. （必須）バージョンを取る：GET https://cloud.leonardo.ai/api/rest/v1/blueprints/<BlueprintのID>/versions。応答に、akUUID（実行に使うバージョンID）、cost（費用）、uiMetadata.inputs（必要な入力。nodeId と settingName がある）が入ります。nodeId と settingName は、この応答のとおりに使います。
  4. 入力を作る：1つの入力は、value、nodeId、settingName の3つです。画像の入力は settingName: "imageUrl"、文字の変数は settingName: "textVariables" で、値は {"name": ..., "value": ...} の配列です。
  5. （必須）実行する：POST https://cloud.leonardo.ai/api/rest/v1/blueprint-executions。本文に blueprintVersionId と input（nodeInputs、public、collectionIds）を入れます。応答の akUUID を控えます。
  6. （任意）状態を見る：GET https://cloud.leonardo.ai/api/rest/v1/blueprint-executions/<akUUID>
  7. （必須）生成のIDを取る：GET .../blueprint-executions/<akUUID>/generations。各項目に status、generationId、failedReason があります。
  8. （必須）出力を取る：GET https://cloud.leonardo.ai/api/rest/v1/generations/<generationId>。画像のアドレスは generations_by_pk.generated_images[].url にあります。

条件と注意

5. 公式SDK（PythonとTypeScript）を使う

公式ドキュメント「Leonardo.Ai Official SDKs」は、PythonとTypeScriptの2つを挙げています。インストールは05のFにあります。ここでは、認証と呼び出しの形を、READMEに沿って書きます。READMEの例は、どちらも、Blueprintを実行する呼び出しです。

Python（READMEの例を短くしたもの。要約経由のため、原文で確認）

from leonardo_ai_sdk import LeonardoAiSDK
from leonardo_ai_sdk.models import shared

with LeonardoAiSDK(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as las_client:

    res = las_client.blueprints.execute_blueprint(request={
        "blueprint_version_id": "550e8400-e29b-41d4-a716-446655440000",
        "input": {
            "collection_ids": [],
            "node_inputs": [
                {
                    "node_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                    "setting_name": shared.SettingName.TEXT,
                    "value": "A futuristic cityscape at sunset",
                },
            ],
            "public": False,
        },
    })

    assert res.one_of is not None
    print(res.one_of)

上の例は、READMEの例から、node_inputs の項目の一部（文字の変数、画像のURLの入力）を省いて、短くしたものです。全文は、GitHubのREADMEにあります。"<YOUR_BEARER_TOKEN_HERE>" の所に、自分のキーを直接書く形は、READMEの書き方ですが、キーをソースコードに書き込むことになります。環境変数を読む形にする方法の一例は、05のEにあります（この記事の案）。

TypeScript（READMEから、認証の部分だけの写し）

import { Leonardo } from "@leonardo-ai/sdk";

const leonardo = new Leonardo({
  bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
});

呼び出しは、leonardo.blueprints.executeBlueprint({...}) の形です。全文はREADMEにあります。

SDKが扱える範囲（READMEの記述）

項目 Python TypeScript
認証 bearer_auth（HTTP Bearer） bearerAuth（HTTP Bearer）
資源のグループ 14のグループ、55のメソッド（READMEの数） 同様のグループ。メソッド名はキャメルケース
主な操作 画像の生成、動画（Motion）、Blueprints、Elements、Models、Dataset、Variation（アップスケールなど）、PricingCalculator、Prompt（改善、ランダム）、User（自分の情報）、3Dのアセット、Realtime Canvas、Texture 同様。Mediaのグループもあり
エラー 基底は LeonardoAiSDKError。status_code、body などを持つ。応答の検証の失敗は ResponseValidationError 基底は LeonardoError。statusCode、body など。ネットワークのエラーも別の型
再試行（リトライ） 一部のエンドポイントで対応。呼び出しごと、または初期化時に設定 同様。retries（呼び出しごと）、retryConfig（初期化時）
注意 ベータ。メジャーバージョンの変更なしに、壊れる変更がありうる。バージョンを固定するよう書かれている READMEにベータの表示は、読んだ範囲では見つからなかった。ログ出力（debugLogger）は、キーなどの秘密が出る可能性があるので、手元の開発でだけ使うよう書かれている

PythonとTypeScriptで、資源のグループに違いがあります（TypeScriptにはMediaがある、PythonにはTextureがある、など）。使う前に、READMEで、使いたい操作があるかを確かめてください。

渡るデータ・外し方

気をつけること

出典