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だけでフレームやテキストを自由に作成・編集できるとは限りません。
あなたはどっち?実行場所から選ぶ判定フロー
REST APIかPlugin APIかは、次の順で決めます。
- 外部のスクリプトから、Figmaの情報を取得したい:REST APIを使います。ファイルをエディターで開かずに取得できます。
- 開いているファイルのレイヤーを作成・編集したい:Plugin APIを使います。現在のファイルのノードを、直接操作できます。
- 別のファイルの情報も必要なプラグインを作りたい:REST APIを併用する設計もできます。Plugin APIが対象にするのは、現在開いているファイルです。
- コメントを外部の管理表へ集めたい:REST APIのコメントのエンドポイントを使います。
- 画像を書き出したい:実行場所で選びます。外部処理はREST API、ファイル内の選択に基づく処理はPlugin APIが候補です。
REST APIだけで、フレームやテキストを自由に作成・編集できるとは限りません。
取得・操作できる情報の比較
| 対象 | REST API | Plugin API |
|---|---|---|
| ファイル名・ノード階層 | ファイルのJSONから取得 | 現在のドキュメントから取得 |
| 更新日時・バージョン履歴 | 該当エンドポイントで取得 | RESTと同じ履歴取得用APIはない |
| コメント | 取得・投稿・削除のエンドポイントあり | 専用のコメント操作APIはない |
| フレーム・図形・テキストの作成や編集 | 一般的なノード編集の用途は対象外 | ノードの作成やプロパティ変更に対応 |
| コンポーネント・スタイル情報 | ファイル情報や該当エンドポイントで取得 | ドキュメント内のノード・スタイルを取得 |
| コンポーネントの挿入 | ノードの挿入は対象外 | ライブラリからのインポート等に対応 |
| 画像の書き出し | レンダリングした画像のURLを取得 | exportAsync()で出力する |
| フォントの一覧・読み込み | Pluginと同じフォント操作APIはない | 利用可能なフォントと読み込みを扱う |
| 独自の操作画面 | 外部アプリ側で作る | プラグインUIを作る |
REST APIは、コメント、変数、Dev Resourcesなど一部の書き込みに対応します。
「REST APIはすべて読み取り専用」という説明では、ノード編集とその他の書き込みを区別できません。
変数のAPIを含め、利用条件はエンドポイントごとに確認します。
REST APIでファイル情報を取得する
ファイル情報の取得先は GET /v1/files/:key です。
返却データにはファイル名、更新日時、バージョン、ドキュメント構造などが含まれます。
階層を制限する depth と、対象ノードを指定する ids は別の条件です。
次は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にはファイルキーも含めます。
投稿する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では生成した画像アセットの有効期間を30日と記載しています。
恒久的な保存先としてURLを使う運用は避け、必要な成果物を取得して管理します。
実際に返る値や書き出せないノードは、検証用ファイルで確認してください。
外部スクリプトで複数のフレームを出力する手順はREST APIによる画像書き出しにまとめています。
Dev Modeで動かすプラグインの制限
Plugin APIでレイヤーを編集できるという比較は、実行環境も含めて判断します。
Dev Modeのプラグインでは、ドキュメント内容の編集はできません。
一部のメタデータの設定、画像書き出し、外部通信、UI表示などは可能です。
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の条件も確認します。
最初は読み取りだけの小さな処理を、専用ファイルで実行します。
プランや席の条件、レート制限、返却データを記録してから、複数ファイルや書き込みへ広げてください。
