# SciFig API 與 MCP 伺服器

透過程式碼或 AI 助手建立科學插圖、圖表和流程圖。網頁版本：https://scifig.ai/zh-Hant/developers。OpenAPI：https://scifig.ai/api/v1/openapi.json。

## 概覽

SciFig API 使用與網站相同的引擎、價格和點數，建立科學插圖、圖表和流程圖。基礎 URL 為 `https://scifig.ai/api/v1`。每次建立均為一個任務：先建立，再讀取狀態和輸出。

AI 助手可透過遠端 MCP 伺服器 `https://mcp.scifig.ai/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 金鑰 → 已連線應用程式中撤銷應用程式。
- 八項權限各自授予，互不包含。上傳檔案、讀取工作與讀取餘額均需分別授權。 `images:generate`, `images:edit`, `images:convert`, `charts:generate`, `flowcharts:generate`, `files:write`, `jobs:read`, `credits:read`
- `GET /api/v1/capabilities` 需要有效憑證，無需業務權限。僅傳回 `granted_scopes`，不傳回餘額、方案或帳號資料。
- 所有已驗證身分的呼叫（含權限拒絕及其他錯誤）均記錄中繼資料，保留30天。不儲存提示詞、內容、檔名、IP或憑證；平台故障時盡力寫入。設定中的金鑰、呼叫紀錄及已連線應用程式各自每頁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"}'
```

響應回傳任務。尚未完成時，狀態為 `202`，攜帶 `Location: /api/v1/jobs/{id}`；每隔幾秒輪詢該 URL，直到 `status` 為 `succeeded`、`failed` 或 `canceled`，再透過 `outputs[].download_url` 下載。

## 約定

- 請求和響應使用 JSON；檔案上傳和圖表資料使用 `multipart/form-data`。欄位名採用 `snake_case`。
- 每個建立內容的 `POST` 都需要 `Idempotency-Key` 請求標頭（1–255 個可見 ASCII 字元）。相同金鑰和相同請求體重試會回傳同一任務，不重複扣費；相同金鑰搭配不同請求體回傳 `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}`，不要換新金鑰。任務已被接納但無法讀回時，回傳 `202` 和 `queued` 狀態。
- `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；其他免費（每天 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 或 1–4 個 `#RRGGBB` 顏色值）、`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`（1–8 個 `#RRGGBB` 顏色值），或自動選擇配色。以上操作均接受 `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 或更高方案；大於零的點數包餘額按 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；DPI 寫入後設資料並決定頁面尺寸，不重新取樣畫素（需更多畫素時先放大）。其原始檔為 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`（多工作表工作簿中的工作表）。無法讀取的資料回傳 `400 INVALID_REQUEST`，包含 `details.field = data` 和 `details.reason` 中的解析器代碼。輸出 PNG、PDF、TIFF 和 EPS。

`POST /charts/edits` 和 `POST /flowcharts/edits`：`job`（此前的圖表或流程圖任務）和 `instruction`（圖表為 1–16,000 個字元，流程圖為 1–8,000 個字元）。編輯從該任務的輸出繼續，保留資料、圖表類型、期刊樣式（圖表）或寬高比（流程圖）。與工作臺一樣，僅最新版本可編輯：存在新版本時（包括網站產生的版本），回傳 `409 REVISION_CONFLICT` 和 `details.reason = NOT_LATEST_REVISION`。父任務仍在執行時回傳可重試的 `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`。失敗任務返還點數。

超時的產生或編輯任務狀態為 `failed`，攜帶 `error.code = TASK_TIMED_OUT` 和 `late_delivery_until` 時間戳：在此時間之前仍可能免費交付，請繼續讀取任務，不要建立新任務。

內容政策拒絕時，建立請求回傳 `422 CONTENT_REJECTED`；若發生在任務執行期間，則任務為 `failed`，帶有 `error.code = CONTENT_REJECTED`。兩種情況均返還點數。

每個輸出包含 `file_id`、`format` 和無需憑證、有效期一小時的 `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`（1–255 個可見 ASCII 字元）使上傳可重放：相同帳戶、金鑰和 `purpose` 以 `201` 回傳首個檔案，不重複上傳或佔用額度；相同金鑰和 `purpose` 搭配不同位元組回傳 `409 IDEMPOTENCY_CONFLICT`。重放已過期上傳回傳 `400 INVALID_REQUEST` 和 `details.reason = FILE_EXPIRED`；請換新金鑰重新上傳。

`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 請求標頭（1–255 個可見 ASCII 字元）。 |
| 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 | 請求數、每小時任務數、每日轉換數或上傳數過多；`details.reason` 說明具體原因。 |
| CONCURRENCY_LIMITED | 429 | 此帳戶執行中的任務過多。 |
| SERVICE_UNAVAILABLE | 503 | 服務暫時不可用。請使用相同 Idempotency-Key 重試。 |
| TASK_FAILED | 502 | 任務失敗，點數已返還。請傳送新請求（使用新的 Idempotency-Key）重試。 |
| INTERNAL_ERROR | 500 | 內部錯誤。 |

`details.reason` 指出 `INVALID_REQUEST`、`PLAN_REQUIRED` 等錯誤的確切原因。只有 `INSUFFICIENT_CREDITS` 包含 `details.top_up_url`；其中 `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 | 任務失敗但未報告原因，點數已返還。 | 使用新金鑰傳送新請求 |

## 速率限制

- 建立：每個憑證每分鐘 20 個請求，每個帳戶每分鐘 40 個請求。OAuth 憑證按用戶端和帳戶計算。
- 讀取：每個憑證每分鐘 120 個請求。
- 執行中任務數按方案限制；每小時最多啟動 200 個任務。兩者均與網站共享。
- 透過驗證和權限檢查的響應攜帶 `X-RateLimit-Limit`、`X-RateLimit-Remaining` 和 `X-RateLimit-Reset`；`429` 攜帶 `Retry-After`。
- `429 RATE_LIMITED` 有多種原因；請讀取 `details.reason` 並參閱[速率限制頁面](/zh-Hant/docs/api/rate-limits)。

## 安裝 SciFig 官方外掛

在 Claude Code 中加入 SciFig 外掛市集，即可安裝遠端 MCP 連線，以及用於設定、插圖、圖表和匯出的四項工作流程技能。

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

- [API 與 MCP 概覽](/zh-Hant/developers)
- [MCP 安裝指南](/zh-Hant/developers/mcp/install.md)
- [API 參考文件](/zh-Hant/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_…`。