# SciFig API と MCP サーバー

コードや AI アシスタントから科学図表、グラフ、フローチャートを作成します。閲覧用の文書：https://scifig.ai/ja/developers。OpenAPI：https://scifig.ai/api/v1/openapi.json。

## 概要

SciFig API は、ウェブサイトと同じエンジン、料金、クレジットで科学図表、グラフ、フローチャートを作成します。ベース URL は `https://scifig.ai/api/v1` です。すべての作成はジョブとして扱います。作成した後、ステータスと出力を読み取ります。

AI アシスタントは `https://mcp.scifig.ai/mcp` のリモート MCP サーバーから SciFig を利用できます（以下の「MCP サーバー」を参照）。

## 認証

`/pricing`、`/openapi.json`、`/openapi.yaml` 以外の各リクエストに `Authorization: Bearer <credential>` を送信します。

- 書き込み権限を含むキーには、有効なサブスクリプションまたは残高のあるクレジットパックが必要です。有効期間は30・90・365日で、読み取り専用キーは無期限にもできます。
- OAuth アクセストークン（`sf_at_…`）：承認後に MCP クライアントに発行され、1 時間有効です。`offline_access` を要求するクライアントには、30 日間有効なリフレッシュトークン（`sf_rt_…`）も発行します。設定 → API キー → 接続済みアプリでアプリのアクセス権を取り消せます。
- 8つのスコープを個別に選択します。暗黙の権限はなく、アップロード、ジョブの読み取り、残高の読み取りにはそれぞれの権限が必要です。 `images:generate`, `images:edit`, `images:convert`, `charts:generate`, `flowcharts:generate`, `files:write`, `jobs:read`, `credits:read`
- `GET /api/v1/capabilities` は有効な認証情報のみを必要とし、業務スコープは不要です。`granted_scopes` のみを返し、残高、プラン、アカウント情報は返しません。
- 権限拒否やその他のエラーを含む認証済みの呼び出しは、メタデータとして30日間保存します。プロンプト、内容、ファイル名、IP、認証情報は保存しません。プラットフォーム障害時の記録はベストエフォートです。設定のキー、呼び出し履歴、接続済みアプリは、それぞれ1ページに10件ずつ表示します。クレジットは関連ジョブの決済結果であり、再送の行を合算しないでください。
- 許可された`CIMD`クライアントのみ `private_key_jwt` を利用できます。公開鍵を使って署名を検証し、リプレイ攻撃を防止します。匿名の動的登録は引き続き `none` または `client_secret_basic` のみを受け付けます。

## クイックスタート

```bash
curl https://scifig.ai/api/v1/images/generations \
  -H "Authorization: Bearer $SCIFIG_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Prefer: wait=25" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Mitochondrial electron transport chain, labelled", "aspect_ratio": "4:3"}'
```

レスポンスはジョブです。未完了なら `Location: /api/v1/jobs/{id}` 付きの `202` を返します。その URL を数秒ごとにポーリングし、`status` が `succeeded`、`failed`、`canceled` のいずれかになったら、`outputs[].download_url` からダウンロードしてください。

## 共通規則

- リクエストとレスポンスは JSON、アップロードとグラフデータは `multipart/form-data` です。フィールド名は `snake_case` です。
- 作成を行うすべての `POST` に、表示可能な ASCII 文字 1～255 文字の `Idempotency-Key` ヘッダーが必要です。同じキーと同じ本文で再試行すると同じジョブを返し、二重課金しません。同じキーで本文が異なると `409 IDEMPOTENCY_CONFLICT` を返します。同じキーの同時リクエストは同じジョブを返すか、先のリクエストの受け付け中に届いた方には `409 IDEMPOTENCY_IN_PROGRESS` を返します。拒否されたリクエスト（`INSUFFICIENT_CREDITS` など）はそのキーに応答を保持するため、チャージやアップグレード後は新しいキーで送信してください。ジョブ作成後の再試行可能なエラー（`429`、`503`、`409 IDEMPOTENCY_IN_PROGRESS`）や `500 INTERNAL_ERROR` には `details.job_id` が含まれます。新しいキーではなく、同じキーで再試行するか `GET /jobs/{job_id}` をポーリングしてください。受け付け済みのジョブを読み戻せなかった場合はステータス `queued` の `202` を返します。
- `Prefer: wait=N`（1～30 秒）はジョブ完了または指定時間の経過までレスポンスの送信を保留します。
- すべてのレスポンスに `X-Request-Id` が含まれます。エラーの構造は `{"error": {"code", "message", "request_id", "details"}}` です。
- API はブラウザーからの CORS 呼び出しに対応していません。サーバーやスクリプトから呼び出してください。

## エンドポイントとクレジット

| エンドポイント | 用途 | クレジット |
| --- | --- | --- |
| POST /images/generations | 科学図表を生成 | 50 / 75 / 100 (standard / advanced / premium) |
| POST /images/edits | 画像編集：指示（マスクで領域を再描画）、白背景、縦横比、配色、文字置換 | 50 / 75 / 100、マスク指定または `replace_text` は 100 |
| POST /images/text-detections | 置換前に画像内の文字を検出 | 0 |
| POST /images/upscales | 2K、4K、8K に高解像度化 | 50 / 100 / 150 |
| POST /images/conversions | SVG、PNG、PDF、TIFF、PPTX に変換（フローチャート SVG は PNG、PDF、TIFF、PPTX へ） | SVG は 150、その他は無料（1 日 200 回） |
| POST /charts/generations | CSV、TSV、Excel データからグラフを作成 | 100 |
| POST /charts/edits | グラフの最新バージョンを変更 | 100 |
| POST /flowcharts/generations | SVG のフローチャートを作成 | 100 |
| POST /flowcharts/edits | フローチャートの最新バージョンを変更 | 100 |
| POST /files | 画像、マスク、フローチャート添付ファイルをアップロード | 0 |
| GET /jobs/{id} | ジョブのステータス、クレジット、ダウンロードリンク | 0 |
| GET /jobs | 最近の自分のジョブ、新しい順（カーソルによるページ分割） | 0 |
| GET /files/{file_id} | ファイルをダウンロード | 0 |
| GET /credits | 残高、プラン、タスク制限 | 0 |
| GET /pricing | すべての操作のクレジット料金（認証不要） | 0 |
| GET /openapi.json | OpenAPI 3.1 仕様（認証不要） | 0 |
| GET /openapi.yaml | 同じ仕様の YAML 版 | 0 |

## リクエストフィールド

`POST /images/generations`：`prompt`（必須）、`aspect_ratio`（`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`）、`quality`（`standard`、`advanced`、`premium`）、`style`、`palette`（プリセット ID または `#RRGGBB` 1～4 色）、`reference_file_ids`（最大 3 個）。一部のモデルや参照画像には有料プランが必要で、エラーでその旨を知らせます。

`POST /images/edits`：`image`（`file_id`）と `operation`。`instruct`（既定値）は `instruction`（最大 2000 文字）と任意の `mask`（PNG。白が変更領域で、マスク使用時は常に `premium` モデル）を受け取ります。`white_background` は背景を白一色に置換します。`aspect_ratio` は画像を `aspect_ratio` に調整します。`recolor` は `palette`（`#RRGGBB` 1～8 色）を適用するか自動選択します。これらはすべて `quality` を受け付けます。`replace_text` は `text_detection`（同じ画像で実行した `POST /images/text-detections` の ID）と `replacements`（`[{"index", "text"}]`）を受け取り、常に `premium` の文字編集モデルを使用します。

`POST /images/text-detections`：`image`。`id`、画像の `width` と `height`、読み順の `texts`（`index`、`text`、`corners`）を返します。無料で、15 分間に 20 回というウェブサイトの検出枠を共有します。

`POST /images/upscales`：`image`、`scale`（`2k`、`4k` は Starter 以上、`8k` は Plus 以上。クレジットパック残高が 0 を超える場合は Pro 相当）。

`POST /images/conversions`：`image`、`format`（`svg`、`png`、`pdf`、`tiff`、`pptx`）。SVG の `vector_mode` は `editable_text`（既定値）または `full_vector` で、入力は PNG、JPEG、WebP です。その他の形式の `dpi` は 300、600、1000 で、メタデータとページサイズに反映し、ピクセルの再サンプリングはしません（ピクセル数を増やすには先に高解像度化）。入力は PNG、JPEG、フローチャート SVG で、WebP は不可、PNG と TIFF は PNG 入力が必要です。フローチャート SVG はサーバーで Arial と Noto フォントを使って描画し、`width`（256～4096、既定値 2048）が長辺のピクセル数を決めます。フォントで表示できない文字は拒否されます。PPTX には描画画像を配置し、編集可能な図形にはしません。

`POST /charts/generations`（`multipart`）：`data`（CSV、TSV、TXT、XLSX、XLS、最大 8 MB。テキストの区切り文字は自動判別）、`request`（描画内容、1～16,000 文字）、任意の `chart_types`（カンマ区切り）、`journal_style`（`default`、`nature`、`science`、`cell`、`plos`、`acs`）、`figure_width`（`single`、`onehalf`、`double`）、`color_palette`、`sheet_name`（複数シートのブックで使用するワークシート）。読み取れないデータは `details.field = data` と `details.reason` に解析コードを含む `400 INVALID_REQUEST` を返します。PNG、PDF、TIFF、EPS を出力します。

`POST /charts/edits` と `POST /flowcharts/edits`：`job`（既存のグラフまたはフローチャートのジョブ）と `instruction`（グラフは 1～16,000 文字、フローチャートは 1～8,000 文字）。そのジョブの出力を継続編集し、グラフのデータ・種類・ジャーナルスタイル、フローチャートの縦横比を保持します。ワークスペースと同じく最新バージョンのみ編集できます。新しいバージョン（ウェブサイトで作成したものを含む）がある場合は `details.reason = NOT_LATEST_REVISION` 付きの `409 REVISION_CONFLICT` を返します。親ジョブが実行中なら再試行可能な `409 REVISION_CONFLICT`（`PARENT_JOB_RUNNING`、`Retry-After` 付き）、失敗済みなら `400 INVALID_REQUEST`（`JOB_NOT_SUCCEEDED`）を返します。

`POST /flowcharts/generations`：`prompt`（1～8,000 文字）、`aspect_ratio`（`auto` または上記の縦横比）、任意の `attachment_file_ids`（最大 8 個、用途 `flowchart_attachment` でアップロード）。SVG を出力します。

## ジョブ

`status` は `queued`、`processing`、`succeeded`、`failed`、`canceled` のいずれかです。`credits` は台帳から取得した `reserved`、`charged`、`refunded` を示します。失敗したジョブは返金されます。

タイムアウトした生成・編集は、`error.code = TASK_TIMED_OUT` と `late_delivery_until` の時刻を持つ `failed` になります。その時刻までは無料で結果が届く可能性があるため、新しいジョブを作らずに読み続けてください。

コンテンツポリシーによる拒否は、作成時の `422 CONTENT_REJECTED`、または実行中に発生した場合の `error.code = CONTENT_REJECTED` を持つ `failed` ジョブです。どちらも返金されます。

各出力には `file_id`、`format`、認証情報なしで 1 時間利用できる `download_url` があります。PNG は `width` と `height` も返します。グラフとフローチャートにはウェブサイトのワークスペースで結果を開く `editor_url` があり、科学図表と変換にはありません。

画像出力（PNG、JPEG、WebP）は `file_id` で画像エンドポイントの `image` や参照画像に渡せます。変換元は最大 20 MB です。PNG、PDF、TIFF、PPTX への変換は PNG、JPEG、フローチャート SVG に対応し、WebP は使用できません。

## ファイル

`POST /files`（`multipart`）：`file` と `purpose`（`image`、`mask`、`flowchart_attachment`）。画像は最大 20 MB の PNG、JPEG、WebP、マスクは最大 8 MB の PNG、フローチャート添付は FlowChart ワークスペース対応形式で最大 32 MB です。`201` と `file_id`、`purpose`、`content_type`、`size_bytes`、`expires_at`、`created_at` を返します。アップロードは 24 時間利用でき、ウェブサイトと枠を共有し、超過すると `429 RATE_LIMITED` を返します。任意の `Idempotency-Key`（表示可能な ASCII 文字 1～255 文字）で再送できます。同じアカウント、キー、`purpose` は再アップロードや枠の消費なしに最初のファイルを `201` で返します。同じキーと `purpose` でバイト列が異なると `409 IDEMPOTENCY_CONFLICT` を返します。期限切れのアップロードを再送すると `details.reason = FILE_EXPIRED` 付きの `400 INVALID_REQUEST` を返すため、新しいキーで再アップロードしてください。

`GET /files/{file_id}` は認証情報、またはジョブの署名付き `download_url` で自分のファイルをダウンロードします。期限切れや改変された署名付きリンクは `404` を返します。利用停止中または削除処理中のアカウントのリンクもすべて同様です。

## エラー

| コード | HTTP | 意味 |
| --- | --- | --- |
| UNAUTHORIZED | 401 | 認証情報が未指定または無効です。 |
| ACCOUNT_UNAVAILABLE | 401 | このアカウントは API を利用できません。 |
| SCOPE_DENIED | 403 | この認証情報に必要な権限がありません。 |
| INVALID_REQUEST | 400 | リクエストが無効です。 |
| IDEMPOTENCY_KEY_REQUIRED | 400 | Idempotency-Key ヘッダー（表示可能な ASCII 文字 1～255 文字）が必要です。 |
| IDEMPOTENCY_CONFLICT | 409 | この Idempotency-Key は別のリクエストですでに使われています。 |
| IDEMPOTENCY_IN_PROGRESS | 409 | この Idempotency-Key のリクエストはまだ処理中です。 |
| NOT_FOUND | 404 | 見つかりません。 |
| REVISION_CONFLICT | 409 | グラフまたはフローチャートのジョブを今は編集できません：`NOT_LATEST_REVISION`、`EDIT_IN_PROGRESS`、または親ジョブの実行中を示す `PARENT_JOB_RUNNING`。 |
| PAYLOAD_TOO_LARGE | 413 | リクエスト本文が大きすぎます。 |
| INSUFFICIENT_CREDITS | 402 | クレジットが不足しています。 |
| CONTENT_REJECTED | 422 | コンテンツポリシーがリクエストを拒否しました。作成時は `422`、タスク実行中は失敗したジョブの `error.code` で返します。どちらも返金されます。 |
| PLAN_REQUIRED | 403 | 現在のプランではこのオプションを利用できません。 |
| RATE_LIMITED | 429 | リクエスト数、1 時間のタスク数、1 日の変換数、またはアップロード数が上限を超えています。`details.reason` が該当する制限を示します。 |
| CONCURRENCY_LIMITED | 429 | このアカウントで実行中のタスクが多すぎます。 |
| SERVICE_UNAVAILABLE | 503 | サービスは一時的に利用できません。同じ Idempotency-Key で再試行してください。 |
| TASK_FAILED | 502 | タスクが失敗し、クレジットは返還されました。再試行するには、新しい Idempotency-Key で新しいリクエストを送信してください。 |
| INTERNAL_ERROR | 500 | 内部エラー。 |

`details.reason` は `INVALID_REQUEST`、`PLAN_REQUIRED` などの詳しい原因を示します。`details.top_up_url` は `INSUFFICIENT_CREDITS` のみに含まれ、`utm_source` はリクエスト経路に応じて `api` または `mcp` です。

失敗したジョブ内にのみ現れるコード：

| error.code | 意味 | 対処方法 |
| --- | --- | --- |
| TASK_TIMED_OUT | タスクがタイムアウトし、返金されました。科学図表の生成・編集には `late_delivery_until` が含まれる場合があり、その時刻までは無料で結果が届く可能性があります。 | `late_delivery_until` までジョブを読み続ける。それ以外は新しいキーで新しいリクエストを送信 |
| CONTENT_REJECTED | タスクの実行中にコンテンツポリシーが結果を拒否しました。返金済みです。作成時にリクエスト自体が拒否された場合も、同じコードを `422` で返します。 | プロンプトまたは入力を変更し、新しいキーを使用 |
| ADMISSION_INCOMPLETE | 再試行可能なエラーにより、ジョブは開始されませんでした。クレジットは使用していません。 | 同じリクエストを同じ Idempotency-Key で送信 |
| TASK_NOT_FOUND | ジョブは受け付けられましたが、対応するタスクが見つからなくなりました。 | 新しいキーで新しいリクエストを送信 |
| TASK_FAILED | タスクが失敗し、返金されました。固有の公開コードがないエンジン障害はすべて `TASK_FAILED` になり、エンジンのコードは `details.reason` に含まれます。 | 新しいキーで新しいリクエストを送信 |
| INTERNAL_ERROR | 理由が報告されずにタスクが失敗しました。返金済みです。 | 新しいキーで新しいリクエストを送信 |

## レート制限

- 作成：認証情報ごとに 1 分 20 件、アカウントごとに 1 分 40 件。OAuth 認証情報はクライアントとアカウントの組み合わせで集計します。
- 読み取り：認証情報ごとに 1 分 120 件。
- 同時実行タスク数はプランに従い、1 時間に開始できるタスクは最大 200 件です。どちらもウェブサイトと共有します。
- 認証とスコープ検証を通過したレスポンスには `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` が含まれ、`429` には `Retry-After` が含まれます。
- `429 RATE_LIMITED` には複数の原因があります。`details.reason` と[レート制限のページ](/ja/docs/api/rate-limits)を参照してください。

## SciFig 公式プラグインをインストール

Claude Code に SciFig マーケットプレイスを追加すると、リモート MCP 接続と、設定・科学図表・グラフ・エクスポート用の 4 つのワークフロースキルをインストールできます。

```text
/plugin marketplace add lilingm963/scifig-plugins
/plugin install scifig@scifig-plugins
```

- [API・MCP の概要](/ja/developers)
- [MCP インストールガイド](/ja/developers/mcp/install.md)
- [API リファレンス](/ja/docs/api)
- [公式プラグインを見る](https://github.com/lilingm963/scifig-plugins)
- [MCP Registry の登録情報](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.lilingm963%2Fscifig/versions/1.0.0)

## MCP サーバー

サーバー URL：`https://mcp.scifig.ai/mcp`（Streamable HTTP）。OAuth 対応クライアントは SciFig にログインしてアクセスを承認して接続します。ヘッダーを送信できるクライアントは、API キーを `Authorization: Bearer sk_live_…` として使用できます。

| ツール | 機能 |
| --- | --- |
| generate_figure | プロンプトから科学図表を作成 |
| edit_figure | 画像編集：指示（任意でマスク領域）、白背景、縦横比、配色、文字置換 |
| detect_text | 置換前に画像内の文字を検出 |
| upscale_figure | 2K、4K、8K に高解像度化 |
| convert_figure | SVG、PNG、PDF、TIFF、PPTX に変換 |
| generate_chart | CSV・TSV テキスト、または JSON 行からグラフを作成（最大 1 MB） |
| edit_chart | グラフの最新バージョンを変更 |
| generate_flowchart | SVG のフローチャートを作成。任意で添付ファイルを最大 8 個使用 |
| edit_flowchart | フローチャートの最新バージョンを変更 |
| get_job | ジョブのステータス、クレジット、ダウンロードリンク |
| list_figures | 最近のジョブ |
| get_credit_balance | クレジット残高、プラン、制限 |

作成ツールは最大 25 秒待機します。ジョブがまだ実行中の場合は後で `get_job` を呼び出してください。作成ツールを再度呼び出すと新しいジョブが作成され、課金されます。結果には各ダウンロードリンクと、グラフ・フローチャートを SciFig エディターで開くリンクが表示されます。

初期化は `/capabilities` を使い、`credits:read` は不要です。各ツールには対応スコープが必要です。外部URLやdata URLのアップロードには `files:write` も必要で、取得前に確認します。`file_id` の再利用には不要です。インライン取得と `get_job` には `jobs:read` が必要です。ない場合はジョブ結果を保持して制限を説明し、無断で権限を追加しません。

## クライアントの接続

Claude（claude.ai、Claude Desktop）：設定 → コネクタ → カスタムコネクタを追加でサーバー URL を入力し、SciFig にログインしてアクセスを許可します。

ChatGPTの`Plugins`でカスタムの非公開MCP接続を追加します。メニューはアカウントによって異なります。

Claude Code：

```bash
claude mcp add --transport http scifig https://mcp.scifig.ai/mcp
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.scifig]
url = "https://mcp.scifig.ai/mcp"
```

Cursorの`Customize` → MCPを開き、既存のサーバーを保持したまま`mcp.json`を編集します。 続いて`Authenticate`を選び、ブラウザーでSciFigを承認します。

```json
{
  "mcpServers": {
    "scifig": {
      "url": "https://mcp.scifig.ai/mcp"
    }
  }
}
```

OAuth 非対応クライアントは、設定 → API キーの API キーで `Authorization: Bearer sk_live_…` ヘッダーを追加できます。