# SciFig API 与 MCP 服务器

通过代码或 AI 助手创建科研插图、图表和流程图。网页版本：https://scifig.ai/zh/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/docs/api/rate-limits)。

## 安装 SciFig 官方插件

在 Claude Code 中添加 SciFig 插件市场，即可安装远程 MCP 连接，以及用于设置、插图、图表和导出的四项工作流技能。

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

- [API 与 MCP 概览](/zh/developers)
- [MCP 安装指南](/zh/developers/mcp/install.md)
- [API 参考文档](/zh/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_…`。