Magnific（旧 Freepik）をほかのAIや編集ソフトにつなぐ手順（その2）：APIキーの作り方、リクエストと結果の受け取り、webhook、制限、キーの管理、AIとの組み合わせ案、外し方の一覧を、公式の記載どおりに

この記事は、公式の資料を2026年10月25日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。コード例は「公式の記載に合わせて、この記事で組んだ例（動作は確かめていません）」で、公式のコードの写しではありません。実際のリクエストの形は、公式のAPIリファレンスで確かめてください。APIキーの実値は、どこにも書いていません。

先に結論

• APIはクレジットを使う購読の仕組みです。 APIのヘルプは、APIは購読とクレジットの仕組みで、生成のリクエストごとにクレジットが引かれる、と書き、プランごとのキーの数を表にしています。03で整理した公式のAPI利用規約は、APIの利用にはAPIを含む有効な購読が要る、と書いていました（この記事では、規約のページは読み直していません）。一方、API用のクイックスタートは、購読の条件を書かず、Enterpriseは担当者にAPIのアクセスを頼む、とだけ書いています（併記）。無料のお試しの記述は、読んだ範囲では見つかりませんでした。
• キーの作り方の画面の経路は、公式のページで複数書かれています。 「いまの経路」「古い経路」「購読の管理者の画面」が併記されています（後述）。
• 結果の画像のURLは、生成から30分で期限が切れます。 公式のクイックスタートに書かれています。取りに行く処理を、30分以内に済ませる必要があります。
• AIアシスタントにコードを書かせるための入口が、公式のドキュメントにあります。 llms.txt、llms-full.txt、各ページのURLの末尾に .md を付けた形、の3つです。
• MCPとAPIは別の入口です。 MCPはOAuthでAPIキーを使わず、APIは秘密のキーを使います（07）。

前提：用語をそろえる

• API：他のソフトからMagnificの機能を呼び出す入口です。
• APIキー：呼び出す側の身元を示す文字列で、ほかの人に見せない秘密として扱います。
• 非同期：リクエストを送ると、まず「受け付けた」という返事（タスクID）が来て、結果はあとで取りに行く、または届く、という形です。
• ポーリング：結果ができたかを、一定の間隔で聞きに行くやり方です。
• webhook：結果ができたときに、こちらが用意したURLへ、Magnificから通知が送られるやり方です。
• HMAC：共有の秘密を使って、メッセージが改ざんされていないかを確かめる計算です。公式のwebhookのページでは、署名の確認に使います。
• レート制限：短い時間に送れるリクエストの数の上限です。
• 環境変数：キーなどの秘密を、コードの中に書かず、実行する環境から渡す仕組みです。

手順1：APIキーを作る

公式のヘルプ「Magnific API」とクイックスタートに書かれた内容を並べます。

書かれている経路

クイックスタート（API用）は、「管理者（Administrator）のメールアドレスでサインインし、ダッシュボードの API Keys でキーを作る」という順を書いています。経路の書き方がページによって違うので、どれが手元の画面で正しいかは、画面と照らして決めてください。

キーを作ったときに起きること

1. キーが作られ、同時に webhookの署名用の秘密 も作られる、と書かれています。
2. キーと秘密は、表示されるのが1回だけ です。窓を閉じる前に、パスワード管理など、決めた保管場所に写します。
3. キーの名前は、秘密や使用履歴を失わずに変えられます。
4. キーは、一時的に無効にできます（キーの入れ替えや緊急時のため、と書かれています）。
5. キーは、確認のうえで完全に削除できます。
6. キーごとに、使用状況を調べられます。

プランごとのキーの数

公式のヘルプ「Magnific API」の表です（確認日 2026-10-25）。

プランごとの月・年のクレジットの数字は、「Magnific API」と「AI credits & limits」の2つのヘルプで、ProとBusinessが食い違って読めたため、この記事には載せません（確認日 2026-10-25）。画面の表示で確かめてください。ストック素材のAPIダウンロードは、Premium、Premium+、Proは、クレジットを使わず1日100回まで、BusinessとEnterpriseは無制限でクレジットから引かれる、と書かれています。

手順2：認証とベースURL

• 認証のヘッダー：x-magnific-api-key
• 呼び出す先：https://api.magnific.com（Mystic のリファレンスにある）。api.freepik.com も動き、同じキーが両方で使える。古い入口は少なくとも6か月は使えて、移行の予定を知らせるヘッダー（deprecation headers）が付く、と移行のページに書かれています（2026年10月25日に再確認）。
• 認証のページに載る例の趣旨を、次のとおり書きます（言語ごとの例の有無は、今回の再確認では確認できていません）。公式の原文は、公式ページで確かめてください。

# この記事で組んだ例（公式の認証のページの趣旨。動作は確かめていません）
curl -H "x-magnific-api-key: YOUR_API_KEY" https://api.magnific.com/v1/resources

• 公式の認証のページは、いまのところ「private API keys」だけが認証の方法で、サーバーとサーバーの間の呼び出しだけが可能になる、したがってキーは、ブラウザなど利用者側のコードに出さず、バックエンドで使うことになる、という趣旨を書いています。保管・入れ替え・取り消しについて、それ以上の案内は、そのページには書かれていません。
• 認証のページは、OpenAPIの仕様書をダウンロードできるリンクがある、とも書いています。

手順3：画像を1枚作る（Mystic）

公式のMysticのリファレンスに書かれた項目です。

リクエスト

• 方法と経路：POST /v1/ai/mystic
• ヘッダー：x-magnific-api-key、本文はJSON
• 主なパラメータ（必須のものは、スキーマ上は示されていません）：

LoRAは、fluid、flexible、super_real、editorial_portraits のモデルのとき、または参照画像を指定したときは、エラーにならず黙って無視される、と書かれています。

この記事で組んだ例（動作は確かめていません）

curl -X POST https://api.magnific.com/v1/ai/mystic \
  -H "Content-Type: application/json" \
  -H "x-magnific-api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "a small wooden cabin by a lake at dawn, mist over the water",
    "resolution": "2k",
    "aspect_ratio": "square_1_1",
    "model": "realism"
  }'

返事（公式の記載）

• 成功すると、data の中に task_id（UUID）、status、generated（できあがった画像のURLの配列）が入る。受け付けた直後は、status が IN_PROGRESS で generated は空、という例が書かれています。
• status の値：CREATED、IN_PROGRESS、COMPLETED、FAILED。

状態を見に行く

• 方法と経路：GET /v1/ai/mystic/{task-id}（task-id は必須の経路のパラメータ）。
• 完了した例では、generated に画像のURLが入り、has_nsfw の配列も付く例がありますが、スキーマには定義されていません。
• 結果のリンクは、生成から30分で期限が切れます（クイックスタート）。
• 公式のMysticのページは、「リクエストごとにwebhookを設定して、生成物を取れるようにする」趣旨を書いています。

この記事で組んだ例：状態を聞きに行くPython（動作は確かめていません）

キーは環境変数 MAGNIFIC_API_KEY から読み、コードに書きません。間隔は、公式に指定がないため、この記事で仮に置いた値です。

import os
import time
import requests

BASE = "https://api.magnific.com"
HEADERS = {
    "x-magnific-api-key": os.environ["MAGNIFIC_API_KEY"],
    "Content-Type": "application/json",
}

body = {"prompt": "a small wooden cabin by a lake at dawn", "resolution": "2k"}
r = requests.post(f"{BASE}/v1/ai/mystic", headers=HEADERS, json=body, timeout=30)
r.raise_for_status()
task_id = r.json()["data"]["task_id"]

while True:
    s = requests.get(f"{BASE}/v1/ai/mystic/{task_id}", headers=HEADERS, timeout=30)
    s.raise_for_status()
    data = s.json()["data"]
    if data["status"] in ("COMPLETED", "FAILED"):
        break
    time.sleep(5)  # 仮の間隔。レート制限は後述

print(data["status"], data.get("generated"))

手順4：webhookで結果を受け取る

公式のドキュメントのうち、webhookのページが書いているのは「受け取ったものの検証」に限られます。webhook_url の渡し方は、Mysticのリファレンスに書かれています（上の表）。

公式のwebhookのページに書かれた検証の方法

再送の回数や間隔、ペイロード（本文）の項目、待ち受けるサーバーのURLの条件は、そのページには書かれていません。Mysticのリファレンスは、通知の本文は状態を聞く経路の返事と同じで、data の包みがない形、と書いています。

この記事で組んだ例：署名の計算（動作は確かめていません）

公式の説明に合わせた形です。秘密の扱い（文字列のまま使うか、base64から戻すか）は、公式の言語別の例を見て合わせてください。

import base64
import hashlib
import hmac

def make_signature(secret: str, webhook_id: str, timestamp: str, body: str) -> str:
    content = f"{webhook_id}.{timestamp}.{body}"
    digest = hmac.new(secret.encode(), content.encode(), hashlib.sha256).digest()
    return base64.b64encode(digest).decode()

# secret には環境変数などから読んだ値を渡す（コードに直接書かない）

手順5：制限とエラー

制限（公式のドキュメント、確認日 2026-10-25）

APIのヘルプは、制限は「APIキーごととIPごと」で、超えると抑えられたり一時的にブロックされたりすることがある、1日の上限（RPD）と画像の上限（IPD）はダッシュボードで確かめる、より高い制限は営業と話して個別のプランにする、と書いています。ドキュメントの制限のページには、制限を知らせるヘッダーの記載も、HTTPの429の記載も、再試行の間隔の案内もありませんでした。

エラー（公式の記載）

手順6：エンドポイントの地図と、AIに渡す入口

ドキュメントの区分（docs.magnific.com/llms.txt、確認日 2026-10-25）

状態を取るGETのページが索引に並ぶのは、Mystic、音楽、効果音、音声の分離の4つでした。動画やアップスケーラーも非同期と書かれていますが、状態のページは、索引からは見つかりませんでした。

AIアシスタントにコードを書かせる入口（公式のドキュメントに書かれたもの）

• https://docs.magnific.com/llms.txt：ドキュメント全体の軽い索引（サイトマップ）
• https://docs.magnific.com/llms-full.txt：ドキュメント全体のMarkdown。AIの文脈の長さを超えることがある、と書かれている
• 各ページのURLの末尾に .md を付けると、そのページがMarkdownで返る

この記事の案：連携を組み合わせる（動作は確かめていません）

公式の記載をつなげて考えた案です。公式の手順ではなく、どの組み合わせも動作を確かめていません。

公式のMCPのドキュメントは、MCPの道具に、images_generate、video_generate、audio_tts、models3d_generate、stock_search のような名前が並ぶと書いています。ここに挙げた組み合わせは、公式がそう使えと書いたものではありません。

連携ごとの「渡るもの・権限・外し方」の一覧

APIの使い方の規則として、公式のヘルプは、データマイニング、スクレイピング、AIの学習に使わない、素材を手を加えずに売ったり再配布したりしない、素材を使うたびにダウンロードを正しく報告する、違反するとすぐアクセスを外される、と書いています。

うまくいかないときの確認点（API）

気をつけること

• この記事は、実際に使って確かめた記録ではありません。コード例は、公式の記載に合わせてこの記事で組んだもので、実行して確かめていません。
• APIキーとwebhookの秘密は、表示が1回だけです。この記事の例ではプレースホルダと環境変数にしています。実際のキーを、AIとの会話、公開リポジトリ、利用者側のコードに入れないでください。
• 公式のドキュメントの複数のページで、同じ項目の書き方が食い違っています（キーの作り方の経路、ProとBusinessのクレジットの数字。数字は載せていません）。画面の表示で確かめてください。
• 公式のドキュメントには、MysticのGETの返事のスキーマの名前が別のエンドポイントのものに見える、という不一致もあります。実際の返事の形は、動かして確かめることになります。
• 取得したドキュメントのページ（docs.magnific.com）には、AIが読むことを想定した一文（「Use this file to discover all available pages before exploring further」）が、ページの頭にありました。この記事は、その指示には従わず、ページの本文だけを根拠にしました。
• 他社のモデルを選んでAPIを呼んだ場合のデータの扱いは、03で整理した公式のプライバシーポリシーの記述が当てはまります。
• エンドポイントの一覧は変わります。この記事に挙げたのは、2026年10月25日に索引で読んだ範囲です。
• 規約・料金・プランは変わります。使う前に、公式で最新を読んでください。この記事は法律の助言ではありません。

出典

• Magnific API（ヘルプ、Magnific、確認日 2026-10-25）
• API Introduction（Magnific、確認日 2026-10-25）
• Quickstart（API、Magnific、確認日 2026-10-25）
• Authentication（API、Magnific、確認日 2026-10-25）
• Webhooks（API、Magnific、確認日 2026-10-25）
• Rate limits（API、Magnific、確認日 2026-10-25）
• Mystic Generate Image（API リファレンス、Magnific、確認日 2026-10-25）
• Mystic Get Task Status（API リファレンス、Magnific、確認日 2026-10-25）
• Docs index（API ドキュメントの索引、Magnific、確認日 2026-10-25）
• Magnific MCP（API ドキュメント内、Magnific、確認日 2026-10-25）
• Freepik is now Magnific（移行の案内、Magnific、確認日 2026-10-25）
• AI credits & limits（ヘルプ、Magnific、確認日 2026-10-25）
• Magnific MCP（Magnific、確認日 2026-10-25）
• Getting started with Spaces（ヘルプ、Magnific、確認日 2026-10-25）