Amazonで商品を見るセール会場へ

Figma REST APIとPlugin APIの違い|できること・取得データ・選び方

Figma APIは、外部スクリプトから情報を取得するならREST API、開いているファイルのレイヤーを作成・編集するならPlugin APIが基本です。

画像の書き出しなど、両方でできる作業もあるため、実行場所と変更したい対象から選びます。

この記事はFigma公式ドキュメントをもとに整理しています。

公式情報の確認日は2026年10月3日です。

コード例は構造を示すためのもので、Figmaに接続した動作検証は未実施です。

目次

作りたいものからAPIを選ぶ

作りたいものAPIの候補選ぶ理由
複数ファイルの情報を外部で集計するREST APIファイルをエディターで開かずに取得する
開いているファイルのレイヤー名を変更するPlugin API現在のファイルのノードを直接操作する
コメントを外部の管理表へ集めるREST APIコメントのエンドポイントを使う
選択中の部品を別のコンポーネントへ差し替えるPlugin API現在の選択とキャンバス上の操作を扱う
画像をまとめて書き出す実行場所で選ぶ外部処理はREST、ファイル内の選択に基づく処理はPluginが候補

Plugin APIは現在開いているファイルが対象です。

別ファイルの情報が必要なプラグインでは、REST APIを併用する設計もできます。

REST APIだけでフレームやテキストを自由に作成・編集できるとは限りません。

Figma公式:APIの比較

スポンサーリンク

あなたはどっち?実行場所から選ぶ判定フロー

REST APIかPlugin APIかは、次の順で決めます。

  1. 外部のスクリプトから、Figmaの情報を取得したい:REST APIを使います。ファイルをエディターで開かずに取得できます。
  2. 開いているファイルのレイヤーを作成・編集したい:Plugin APIを使います。現在のファイルのノードを、直接操作できます。
  3. 別のファイルの情報も必要なプラグインを作りたい:REST APIを併用する設計もできます。Plugin APIが対象にするのは、現在開いているファイルです。
  4. コメントを外部の管理表へ集めたい:REST APIのコメントのエンドポイントを使います。
  5. 画像を書き出したい:実行場所で選びます。外部処理はREST API、ファイル内の選択に基づく処理はPlugin APIが候補です。

REST APIだけで、フレームやテキストを自由に作成・編集できるとは限りません。

取得・操作できる情報の比較

対象REST APIPlugin API
ファイル名・ノード階層ファイルのJSONから取得現在のドキュメントから取得
更新日時・バージョン履歴該当エンドポイントで取得RESTと同じ履歴取得用APIはない
コメント取得・投稿・削除のエンドポイントあり専用のコメント操作APIはない
フレーム・図形・テキストの作成や編集一般的なノード編集の用途は対象外ノードの作成やプロパティ変更に対応
コンポーネント・スタイル情報ファイル情報や該当エンドポイントで取得ドキュメント内のノード・スタイルを取得
コンポーネントの挿入ノードの挿入は対象外ライブラリからのインポート等に対応
画像の書き出しレンダリングした画像のURLを取得exportAsync()で出力する
フォントの一覧・読み込みPluginと同じフォント操作APIはない利用可能なフォントと読み込みを扱う
独自の操作画面外部アプリ側で作るプラグインUIを作る

REST APIは、コメント、変数、Dev Resourcesなど一部の書き込みに対応します。

「REST APIはすべて読み取り専用」という説明では、ノード編集とその他の書き込みを区別できません。

変数のAPIを含め、利用条件はエンドポイントごとに確認します。

公式API比較の制限事項、変数API

REST APIでファイル情報を取得する

ファイル情報の取得先は GET /v1/files/:key です。

返却データにはファイル名、更新日時、バージョン、ドキュメント構造などが含まれます。

階層を制限する depth と、対象ノードを指定する ids は別の条件です。

Figma公式:ファイルAPI

次はPythonとrequestsを使う例です。

環境変数にはアクセス可能な検証用ファイルのキーと、必要なスコープを持つトークンを設定します。

認証情報をソースへ直接書かないようにします。

import os
import requests

token = os.environ["FIGMA_TOKEN"]
file_key = os.environ["FIGMA_FILE_KEY"]

response = requests.get(
    f"https://api.figma.com/v1/files/{file_key}",
    headers={"X-Figma-Token": token},
    params={"depth": 1},
    timeout=30,
)
response.raise_for_status()
data = response.json()
print({"name": data["name"], "version": data["version"]})

depth=1 はページまでの構造を取得する設定です。

エンドポイントごとに返る項目と回数制限は、Figma APIで取得できる情報一覧にまとめました。

この結果だけで、下位のコンポーネントが空か、削除されたかを判断しないでください。

必要なノードはそのIDを指定して取得し直します。

空のコンポーネントを点検する際の注意

コメントを取得・投稿・削除する場合

作業エンドポイント
コメント一覧を取得GET /v1/files/:key/comments
コメントを投稿POST /v1/files/:file_key/comments
コメントを削除DELETE /v1/files/:file_key/comments/:comment_id

取得は file_comments:read、投稿・削除は file_comments:write のスコープが必要です。

削除できるのは自分が投稿したコメントです。

URLにはファイルキーも含めます。

Figma公式:コメントAPI

投稿するJSONに説明用コメントを入れると、そのままではJSONとして解析できません。

例の注釈と送信するデータを分けます。

取得と出力の詳しい手順はコメントAPIの記事を参照してください。

Plugin APIで現在のファイルを操作する

Plugin APIでは figma オブジェクトを通して、ノード、選択状態、スタイルなどを扱います。Figma公式:Plugin APIリファレンス

現在のページのコンポーネントを探す場合は、次のようにノードを検索できます。

これはファイル全体を走査する例ではありません。

const components = figma.currentPage.findAllWithCriteria({
  types: ["COMPONENT"],
});

console.log(components.map(node => ({
  id: node.id,
  name: node.name,
  key: node.key,
})));

ファイル全体を調べる場合は、ページの読み込み条件も確認します。

フォントの読み込みとページの読み込みは別の処理です。

API名と使用条件は公式の型定義で確認できます。

開発を始める手順はプラグイン開発入門へ進んでください。

画像書き出しの違い

REST APIの GET /v1/images/:key は、指定したノードをレンダリングした画像のURLを返します。

Plugin APIの exportAsync() は、画像形式ではファイルのバイト列を返します。

画像書き出しをREST APIだけの機能として分類しないようにします。

公式ファイルAPI、公式exportAsync

公式ファイルAPIでは生成した画像アセットの有効期間を30日と記載しています。

恒久的な保存先としてURLを使う運用は避け、必要な成果物を取得して管理します。

実際に返る値や書き出せないノードは、検証用ファイルで確認してください。

外部スクリプトで複数のフレームを出力する手順はREST APIによる画像書き出しにまとめています。

Dev Modeで動かすプラグインの制限

Plugin APIでレイヤーを編集できるという比較は、実行環境も含めて判断します。

Dev Modeのプラグインでは、ドキュメント内容の編集はできません。

一部のメタデータの設定、画像書き出し、外部通信、UI表示などは可能です。

Figma公式:Dev Modeでの開発

Dev Modeではページが動的に読み込まれ、最初にアクセスできるのは現在のページが基本です。

ファイル全体を走査する処理は、必要なページを読み込む設計にします。

対応するエディターと実行モードは、manifest、figma.editorType、figma.modeで確認します。

実行モードの公式説明

よくある質問:REST APIとPlugin APIで迷ったときのチェックリスト

画像の書き出しは、REST APIだけの機能ですか?

いいえ。

REST APIのGET /v1/images/:keyは、指定したノードをレンダリングした画像のURLを返します。

Plugin APIのexportAsync()は、画像形式ではファイルのバイト列を返します。

両方でできます。

REST APIで返る画像のURLは、ずっと使えますか?

使えません。

公式のファイルAPIでは、生成した画像アセットの有効期間を30日と記載しています。

恒久的な保存先としてURLを使う運用は避け、必要な成果物を取得して管理してください。

Dev Modeのプラグインで、ドキュメントを編集できますか?

できません。

Dev Modeのプラグインでは、ドキュメント内容の編集はできません。

一部のメタデータの設定、画像書き出し、外部通信、UI表示などは可能です。

Dev Modeで、ファイル全体を走査できますか?

Dev Modeではページが動的に読み込まれ、最初にアクセスできるのは現在のページが基本です。

ファイル全体を走査する処理は、必要なページを読み込む設計にします。

REST APIの認証は、何を確認しますか?

トークンやOAuthによる認証に加えて、スコープと、ファイルへのアクセス権を確認します。

最初は、何から試すのがよいですか?

読み取りだけの小さな処理を、専用ファイルで実行します。

プランや席の条件、レート制限、返却データを記録してから、複数ファイルや書き込みへ広げてください。

スポンサーリンク

認証・権限・実行条件の確認

REST APIではトークンやOAuthによる認証に加え、スコープとファイルへのアクセス権を確認します。

Plugin APIで現在のキャンバスを扱うことと、プラグインから外部サービスへ通信することは、設定が異なります。

外部通信はmanifestの条件も確認します。

最初は読み取りだけの小さな処理を、専用ファイルで実行します。

プランや席の条件、レート制限、返却データを記録してから、複数ファイルや書き込みへ広げてください。

個人アクセストークンの設定

サービス

Service

デザイン制作に関心がありましたら、ぜひ詳細をご覧ください。

次に学ぶ・作業環境を選ぶ

学習を続けたい方や、作業環境を整えたい方は、目的に合うガイドをご覧ください。

Figmaのおすすめ書籍

Figma用PCの選び方

周辺機器の優先度

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!
目次