API 参考文档

文件

上传输入文件并下载输出结果。

上传#

POST /files 接受 multipart/form-data，需要 figures:generate 权限范围。成功返回 201，包含 file_id、purpose、content_type、size_bytes、expires_at 和 created_at。

字段	类型	必填	默认值	规则
file	file	是	—	参阅下方用途限制
purpose	string	否	`image`	`image`、`mask` 或 `flowchart_attachment`

用途	支持的输入	使用场景
image	PNG、JPEG 或 WebP，最大 20 MB（按内容校验，而非文件名）	编辑、文字识别、放大、转换、参考图像
mask	最大 8 MB 的 PNG；白色标记需要重绘的区域	`POST /images/edits`
flowchart_attachment	FlowChart 工作台支持的格式，最大 32 MB	`POST /flowcharts/generations`

上传文件可使用 24 小时；之后 file_id 不再有效（400 INVALID_REQUEST、FILE_NOT_FOUND）。它们仅作为输入，不会出现在任务响应中，也不会与任何人共享。

上传与网站共享上传限制。超出限制时，返回 429 RATE_LIMITED，包含 Retry-After 和 details.reason：每分钟限制为 UPLOAD_RATE_LIMITED，每日限制为 UPLOAD_DAILY_LIMIT_REACHED（流程图附件）。

上传可选带 Idempotency-Key 请求头（1–255 个可见 ASCII 字符）。相同账号、密钥和 purpose 始终对应同一个 file_id：重复请求以 201 返回首个文件，不会再次上传或占用上传额度。相同密钥和 purpose 搭配不同字节会返回 409 IDEMPOTENCY_CONFLICT。未发送此请求头时，每次上传均创建新文件。若文件已到期，重放请求返回 400 INVALID_REQUEST 和 details.reason = FILE_EXPIRED；请换新密钥重新上传。

下载#

每个任务输出都有一个无需凭据、有效期一小时的 download_url；重新读取任务即可获得新链接。携带凭据调用 GET /files/{file_id} 可下载你的任意文件。所有文件均以附件形式提供。

签名 download_url 到期或被篡改时返回 404 NOT_FOUND；账号被封禁或正在删除时，其所有下载链接也会以相同方式失效。

输出	可传给
PNG 或 JPEG	所有图像端点（编辑、文字识别、放大、转换、参考图像）
WebP	编辑、文字识别、放大、SVG 矢量化和参考图像；不适用于 PNG、PDF、TIFF 或 PPTX 转换
流程图 SVG	通过 `POST /images/conversions` 转换为 PNG、PDF、TIFF 或 PPTX
PDF、TIFF、EPS、PPTX、其他 SVG	均不可：只能下载

转换源文件大于 20 MB 时（例如放大至 8K 的图像），返回 400 INVALID_REQUEST（FILE_TOO_LARGE）。

cURL#

curl -X POST https://scifig.ai/api/v1/files \
  -H "Authorization: Bearer $SCIFIG_API_KEY" \
  -F "file=@figure.png" \
  -F "purpose=image"

JavaScript#

import { readFile } from 'node:fs/promises';

const form = new FormData();
form.set('file', new Blob([await readFile('figure.png')]), 'figure.png');
form.set('purpose', 'image');

const response = await fetch('https://scifig.ai/api/v1/files', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SCIFIG_API_KEY}`,
  },
  body: form,
});
const result = await response.json();
console.log(response.status, result);

Python#

import os

import requests

headers = {
    "Authorization": f"Bearer {os.environ['SCIFIG_API_KEY']}",
}
response = requests.post(
    "https://scifig.ai/api/v1/files",
    headers=headers,
    files={"file": open("figure.png", "rb")},
    data={"purpose": "image"},
    timeout=60,
)
print(response.status_code, response.json())

上一页鉴权与幂等性下一页图像生成根据文字提示词生成科研插图，也可通过参考图像引导生成。