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

Figmaの情報を外部スクリプトから取得するならREST API、開いているファイルのレイヤーを作成・編集するならPlugin APIが基本です。画像の書き出しなど、両方でできる作業もあるため、実行場所と変更したい対象から選びます。

この記事はFigma公式ドキュメントをもとに整理しています。公式情報の確認日は2026年10月3日です。コード例は構造を示すためのもので、Figmaに接続した動作検証は未実施です。

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

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 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 はページまでの構造を取得する設定です。この結果だけで、下位のコンポーネントが空か、削除されたかを判断しないでください。必要なノードはその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の条件も確認します。

最初は読み取りだけの小さな処理を、専用ファイルで実行します。プランや席の条件、レート制限、返却データを記録してから、複数ファイルや書き込みへ広げてください。個人アクセストークンの設定