5 分钟快速开始

生成第一张科研图

只需一个 API 密钥和两个请求字段。按照以下步骤提交科研图、检查进度并下载结果。

1为钱包充值通过 Stripe 至少充值 $10。

2创建 API 密钥密钥显示后请立即复制，只会显示一次。

3使用服务器或终端切勿在浏览器代码中暴露密钥。

保存 API 密钥

将 fl_live_... 替换为控制台中的密钥。使用环境变量可避免将密钥写入代码。

export FIGURELABS_API_KEY="fl_live_..."

提交生成请求

这个最简请求会让 FigureLabs 根据文字创建一张新科研图。

curl -X POST https://api.figurelabs.ai/v1/images/generations \
  -H "Authorization: Bearer $FIGURELABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt":"Create a clean scientific figure of the PI3K-AKT signaling pathway",
    "mode":"generations"
  }'

prompt必填

描述你想要的科研图。英文提示词通常能生成更可预测的标注和科学细节。

mode可选

常见图像工作流请使用 generations。省略 mode 时，这也是默认值。

保存任务 ID

生成任务在后台运行。首次响应表示任务已被接受，此时尚不包含最终图像。

HTTP/1.1 202 Accepted
{
  "task_id": "tsk_01JZ9F7KQ2",
  "status": "processing",
  "estimated_price": 80,
  "currency": "USD"
}

价格字段以美分为单位。 80 表示 $0.80，而不是 $80。

检查结果

使用返回的 task_id。每隔 2–5 秒检查一次，直到任务进入最终状态。

curl https://api.figurelabs.ai/v1/tasks/tsk_01JZ9F7KQ2 \
  -H "Authorization: Bearer $FIGURELABS_API_KEY"

pending / processing等待后再次检查。

succeeded下载 output_url。

failed / rejected读取 error。此任务不会收费。

下载科研图

任务成功后，从 output_url 保存文件。签名结果 URL 的有效期为七天。

{
  "status": "succeeded",
  "output_url": "https://files.figurelabs.ai/presigned/...",
  "output_type": "image/png",
  "actual_price": 80
}

下一步： 打开 Choose a workflow，可以编辑图像、重新着色、高清放大或生成 SVG 流程图。

指南

生成功能

所有常见的图像生成和编辑任务都使用 POST /v1/images/generations。generations 模式允许 FigureLabs 根据提示词、源文件、配色方案和目标宽高比推断用户意图。

公开 mode 值

mode	适用场景	必需输入
`generations`	Text generation, sketch conversion, reference generation, enhancement, recoloring, and aspect-ratio editing. This is the default when mode is omitted.	Prompt and/or source files, depending on the task.
`region_redraw`	Force the regional-redraw processing path.	Prompt, original image, and one mask.
`white_background`	Force the white-background processing path.	Image or sessionId; prompt is optional.

generations 内部推断的功能

Text to FigurePrompt only; creates a new scientific figure.自动路由

Sketch to FigurePrompt plus a rough sketch image.自动路由

Reference to FigurePrompt plus a visual or layout reference.自动路由

EnhanceExisting image plus an enhancement instruction.自动路由

RecolorExisting image, recolor instruction, and optional colorPalette.自动路由

Aspect RatioExisting image and optional targetRatio. If omitted, FigureLabs selects a suitable ratio for the task.自动路由

示例

{
  "mode": "generations",
  "prompt": "Recolor this pathway using a restrained blue and green palette",
  "files": ["file_image123"],
  "colorPalette": "#2563EB,#14B8A6"
}

固定 mode 值可以安全复用。 Unlike an Idempotency-Key, mode=generations is only a routing value. Every POST request still creates a new task.

指南

文件上传与存储

上传本地图像或文档以获取 file_id，然后将该 ID 传入生成或流程图请求。上传的文件是临时 API 输入，并非永久云存储。

自助存储等级

A new self-serve account starts with 0 storage until its first successful wallet top-up. A successful top-up moves the account to the matching storage tier. The achieved quota does not decrease when API usage later reduces the wallet balance. All API keys under the same account share this limit.

充值后的钱包累计金额	文件存储空间
$0 before first top-up	0 GB
More than $0 and up to $10	1 GB
More than $10 and up to $50	2 GB
More than $50 and below $200	5 GB
$200 or more	20 GB

企业账户

Enterprise storage allowance is defined in the enterprise agreement and is not calculated from wallet balance. If the agreement does not specify a custom allowance, the default is 50 GB. Contact enterprise support to confirm or change the contracted allowance.

文件有效期与删除

Uploaded files are valid for 7 days. After 7 days, a file can no longer be used through the external API by file_id and is not counted toward file storage.

Deleting a file makes its file ID unavailable immediately and removes it from the storage calculation.
The console shows metadata and a Delete action only. It does not preview, open, or download uploaded file content.

上传并使用本地文件

curl -X POST https://api.figurelabs.ai/v1/files \
  -H "Authorization: Bearer $FIGURELABS_API_KEY" \
  -F "file=@./reference.png" \
  -F "purpose=image_generation"

{ "id": "file_abc123", "expires_at": "2026-08-11T10:22:00Z" }

{
  "mode": "generations",
  "prompt": "Redraw this as a clean publication figure",
  "files": ["file_abc123"]
}

指南

模型、速度与宽高比

使用可选的 model 字段锁定模型。省略时，FigureLabs 会选择 API 密钥允许且兼容当前工作流和宽高比的推荐模型。

首次集成时： omit model. Specify it only when you need stable model behavior, reproducibility, or model comparisons.

模型值	显示名称	大约耗时	支持的 targetRatio 值
`gemini-3-pro-image-preview`	Nano Banana Pro	~30 sec	16:9, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 21:9
`nano-banana-2`	Nano Banana 2	~30 sec	16:9, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 21:9
`gpt-image-2`	GPT Image 2	~90 sec	16:9, 1:1, 2:3, 3:2, 4:5, 5:4, 9:16
`nano-banana`	Nano Banana	~15 sec	16:9, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 21:9
`gpt-image-1`	GPT Image 1.5	~90 sec	3:2, 1:1, 2:3
`seedream-5-0-260128`	Seedream 5.0 Lite	~120 sec	16:9, 1:1, 2:3, 3:4, 9:16, 3:2, 4:3, 21:9
`seedream-4-5-251128`	Seedream 4.5	~30 sec	16:9, 1:1, 2:3, 3:4, 9:16, 3:2, 4:3, 21:9
`flux-kontext-max`	Flux.2 Max	~15 sec	4:3, 1:1, 16:9, 9:16, 21:9, 2:3, 5:1, 3:2, 3:7, 7:3
`sora-image`	Sora	~90 sec	3:2, 1:1, 2:3

宽高比选择方式

Image generation uses targetRatio; Flowcharts uses ratio. Use colon notation such as 16:9, not pixels or a display label.

16:91:12:33:23:44:34:55:49:1621:9

If a model is specified, choose one of its supported ratios.
If no targetRatio is sent, FigureLabs determines a suitable output ratio from the prompt, source files, and generation task.
If no model is sent, FigureLabs selects a compatible model using the prompt, input type, requested targetRatio, and available models for the API key.

403 MODEL_NOT_ALLOWED means the API key cannot use that model. 422 MODEL_MODE_NOT_SUPPORTED means the selected model cannot perform the workflow.

指南

控制生成结果

基础生成需要提示词和工作流。仅在需要更多控制时添加模型、宽高比、风格、配色、格式或会话字段。

prompt有条件

Maximum 2,000 characters. Required for generation and edit modes that need instructions.

mode可选

Defaults to generations. Public values are generations, region_redraw, and white_background.

model可选

Lock a model. Omit it to use the recommended compatible model.

targetRatio有条件

Optional. Send a supported ratio to force the output shape; omit it to let FigureLabs choose a suitable ratio from the generation task.

style可选

Flat, 3D, 2.5D, hand_drawn, or line_art. Default: Flat.

format可选

png by default. vector generates then vectorizes to SVG.

quality可选

V1 supports only high. It is the default and does not change price.

sessionId可选

Continue an existing conversation. Omit it to create a new session.

colorPalette可选

Pass 1–8 comma-separated colors in #RRGGBB format. The palette guides the model, especially for recolor, but does not strictly limit every output color. Omit it or pass an empty string to let the model choose.

示例

{
  "model": "nano-banana",
  "prompt": "Create a publication-ready mitochondrial pathway figure",
  "mode": "generations",
  "style": "Flat",
  "targetRatio": "16:9",
  "colorPalette": "#0F172A,#2563EB,#14B8A6",
  "format": "png"
}

API 参考

生成与编辑图像

使用一个端点处理文本生成、草图和参考图工作流、图像增强、局部重绘、重新着色、白色背景和宽高比编辑。

POST/v1/images/generations202 Accepted

请求体application/json

标准价格$0.80; vector total $1.30

OutputPNG or SVG

命名兼容性： this endpoint keeps camelCase fields such as targetRatio, sessionId, and colorPalette. Responses use snake_case.

请求参数

字段	类型	是否必填？	说明
`model`	string	可选	Model value from Models & ratios. Omit for recommended routing.
`prompt`	string	Conditional	Maximum 2,000 characters. Required for generation and instruction-driven edits.
`sessionId`	string	可选	Continue an existing session; a new session is created when omitted.
`mode`	string	可选	Routing mode. Default: generations. Other values: region_redraw and white_background.
`style`	string	可选	Flat, 3D, 2.5D, hand_drawn, or line_art. Default: Flat.
`colorPalette`	string	可选	1–8 comma-separated #RRGGBB colors used as visual guidance.
`imageUrl`	string / object / array	可选	Legacy-compatible reference input: URL, Data URI, file object, file ID, or array.
`files`	string / object / array	可选	Image or document inputs. Merged with imageUrl.
`mask`	string / object	Conditional	One image; required and only valid for region_redraw.
`targetRatio`	string	Conditional	Optional ratio such as 16:9. Omit it to let FigureLabs choose a suitable ratio for the generation task.
`format`	string	可选	png (default) or vector. Vector runs generation plus SVG conversion.
`quality`	string	可选	V1 supports only high; default high; no price change.
`quoteMessageId`	number	可选	Message to edit. Requires sessionId; otherwise ignored.
`safetyIdentifier`	string	可选	Your non-sensitive end-user reference for safety auditing.

路由模式

mode	行为	输入要求
`generations`	Agent automatically identifies text, sketch, reference, enhance, recolor, or aspect-ratio intent.	Prompt and/or source files. Default when omitted.
`region_redraw`	Fixed regional-redraw processing.	Prompt, original image, and one mask.
`white_background`	Fixed white-background processing.	Image or sessionId; prompt optional.

请求示例

Text to figure

{
  "model": "gpt-image-2",
  "prompt": "A publication-ready mitochondrial metabolism pathway",
  "mode": "generations",
  "style": "Flat",
  "colorPalette": "#111111,#2F80ED,#27AE60",
  "targetRatio": "16:9",
  "format": "png"
}

Reference image

{
  "model": "nano-banana",
  "prompt": "Redraw this as a clean Nature-style schematic",
  "mode": "generations",
  "imageUrl": "https://example.com/input/figure.png",
  "targetRatio": "4:3"
}

Regional redraw with mask

{
  "prompt": "Redraw the masked area as a microscope panel",
  "mode": "region_redraw",
  "files": ["file_image123"],
  "mask": "file_mask123"
}

创建响应

字段	类型	含义
`task_id`	string	Save this ID and query Tasks.
`session_id`	string	Use it to continue the same session.
`status`	string	Usually processing.
`estimated_price`	number	Estimated hold in USD cents.
`currency`	string	USD in V1.

API 参考

高清放大图像

将一张栅格图放大至 2K、4K 或 8K。任务成功后的输出格式为 PNG。

POST/v1/images/upscale202 Accepted

InputFirst valid bitmap image

Target2K, 4K, or 8K

Outputimage/png

请求参数

字段	类型	是否必填？	说明
`image_url`	string / object / array	必填	URL, Data URI, file object, or file ID. If an array is sent, the first valid image is used.
`target_size`	string	可选	2k, 4k, 8k, or width x height such as 4096x2048. Default: 2K tier.
`safety_identifier`	string	可选	Your non-sensitive end-user reference.

目标等级与价格

值	目标长边	标准价格
`2k` or omitted	Approximately 2,048 px	$0.02
`4k`	Approximately 4,096 px	$0.04
`8k`	Approximately 8,192 px	$0.08
`4096x2048`	Larger dimension selects the tier	$0.04

建议： send 2k, 4k, or 8k. Preset tiers avoid ambiguity when custom dimensions are converted to pricing tiers.

示例

{
  "image_url": "https://example.com/input/source.png",
  "target_size": "4k",
  "safety_identifier": "user_12345"
}

{ "task_id": "tsk_...", "session_id": "ses_...", "status": "processing", "estimated_price": 4, "currency": "USD" }

API 参考

矢量化图像

将一张栅格图转换为可缩放 SVG。V1 每个任务处理一张图像。

POST/v1/images/vectorize202 Accepted

InputOne raster image

标准价格$0.50

Outputimage/svg+xml

请求参数

字段	类型	是否必填？	说明
`image_url`	string / object	必填	One bitmap URL, Data URI, file object, or file ID.
`safety_identifier`	string	可选	Your non-sensitive end-user reference.

Do not rely on the historical image_urls batch field. Public V1 returns one output URL and supports one image per task.

示例

{
  "image_url": "https://example.com/input/chart.png"
}

{ "task_id": "tsk_...", "session_id": "ses_...", "status": "processing", "estimated_price": 50, "currency": "USD" }

新建生成： use format=vector in Generate & edit to generate and vectorize in one task. The standard total is $1.30.

API 参考

生成流程图

根据提示词和可选的图像或文档输入创建 SVG 研究流程图。

POST/v1/flowcharts202 Accepted

InputPrompt; optional files

标准价格$0.80

OutputSVG

请求参数

字段	类型	是否必填？	说明
`prompt`	string	必填	Non-empty flowchart instruction.
`session_id`	string	可选	Continue an existing session; creates a new session when omitted.
`ratio`	string	可选	Output ratio such as 16:9 or 1:1.
`file_url`	string / object / array	可选	Legacy single-file field; also accepts file object, file ID, or array.
`files`	string / object / array	可选	URL, Data URI, file object, or file ID array. Merged with file_url.

示例

{
  "prompt": "Draw a single-cell RNA-seq workflow from tissue dissociation to marker annotation",
  "ratio": "16:9"
}

使用源文件

{
  "prompt": "Convert this rough process sketch into a polished SVG flowchart",
  "ratio": "4:3",
  "files": ["file_sketch123"]
}

{ "task_id": "tsk_...", "session_id": "ses_...", "status": "processing", "estimated_price": 80, "currency": "USD" }

API 参考

文件

上传临时任务输入，并在开发者控制台中管理已上传文件的元数据。

POST/v1/files201 Created

请求体multipart/form-data

Image limit16 MiB per file

Document limit32 MiB per file

上传要求

Uploads must pass authentication, file-type, file-size, and account storage-limit checks. Rejected uploads are not stored or counted toward account usage.

表单字段

字段	类型	是否必填？	说明
`file`	file	必填	Image or document. Video and audio are not supported.
`purpose`	string	可选	general, image_generation, flowchart, or mask. Default: general.

响应字段

字段	说明
`id`	File ID to pass to a task request.
`file_name`, `mime_type`, `size`	Uploaded-file metadata.
`created_at`, `expires_at`	UTC upload time and the 7-day external expiry time.

上传示例

curl -X POST https://api.figurelabs.ai/v1/files \
  -H "Authorization: Bearer $FIGURELABS_API_KEY" \
  -F "file=@./reference.pdf" \
  -F "purpose=image_generation"

{
  "id": "file_abc123",
  "file_name": "reference.pdf",
  "mime_type": "application/pdf",
  "size": 204800,
  "created_at": "2026-08-04T10:22:00Z",
  "expires_at": "2026-08-11T10:22:00Z"
}

管理和删除文件

Open Developer console → Files to review uploaded-file metadata or delete a file. Deletion requires confirmation.

After deletion, the file_id becomes unavailable immediately and the file no longer counts toward file storage. Already-submitted tasks continue. Data retention follows the FigureLabs privacy policy.

存储限额错误

HTTP	errorCode	含义
413	`STORAGE_QUOTA_EXCEEDED`	The new file would exceed the account's file storage limit.

释放空间： delete files from Developer console → Files, wait for old uploads to expire, or increase the applicable account quota. Self-serve quotas can only move up after a successful top-up; enterprise quotas are managed by operations.

API 参考

查询任务结果

生成、高清放大、矢量化和流程图任务共用同一个任务端点。密钥只能查询所属账户中的任务。

GET/v1/tasks/{task_id}200 OK

路径参数

参数	类型	是否必填？	说明
`task_id`	string	必填	ID returned by a task creation endpoint; usually starts with tsk_.

响应字段

字段	类型	说明
`task_id`	string	Task ID.
`session_id`	string	Session ID for follow-up generation.
`status`	string	pending, processing, succeeded, failed, rejected, or canceled.
`output_url`	string / null	Seven-day signed result URL after success.
`output_type`	string / null	For example image/png, image/svg+xml, png, or svg.
`error`	object / null	Error details for failed or rejected tasks.
`error.code`	string	Public task error code.
`error.message`	string	Human-readable task error.
`actual_price`	number / null	Final charge in USD cents after success.
`estimated_price`	number / null	Estimated hold in USD cents.
`currency`	string / null	USD in V1.
`created_at`	string / null	UTC RFC 3339 time, ending in Z.
`finished_at`	string / null	Completion time; null until finished.

轮询建议

Poll every 2–5 seconds.
Use a longer interval for slower models such as gpt-image-2 and seedream-5-0-260128.
Stop when status is succeeded, failed, rejected, or canceled.
Persist task_id so a network interruption does not lose the result lookup.

请及时下载： output_url is a signed URL valid for seven days. Copy the file to your own permanent storage.

成功结果

{
  "task_id": "tsk_01JZ9F7KQ2",
  "status": "succeeded",
  "output_url": "https://files.figurelabs.ai/presigned/...",
  "output_type": "image/png",
  "error": null,
  "actual_price": 80,
  "estimated_price": 80,
  "currency": "USD",
  "created_at": "2026-07-31T10:20:30Z",
  "finished_at": "2026-07-31T10:21:02Z"
}

失败或被拒绝的任务

actual_price is null and the estimated hold is released. Use UPSTREAM_FAILED for processing failure and UPSTREAM_SAFETY_REJECTED for a safety refusal.

资源

错误处理

根据 FigureLabs 是否已创建任务采用不同的错误处理方式。

HTTP error

Authentication, balance, permission, or validation failed before task creation. Read the top-level error response.

Task error

A task exists but finishes as failed or rejected. Query Tasks and read its error object. It is not charged.

HTTP 错误格式

{
  "code": 401000,
  "errorCode": "INVALID_API_KEY",
  "message": "Invalid API key.",
  "requestId": "req_abc123"
}

常见 HTTP 错误

HTTP	errorCode	具体含义	建议操作
401	`INVALID_API_KEY`	Key missing, malformed, or unknown.	Check the Authorization header.
401	`API_KEY_REVOKED`	The key was permanently revoked.	Create and use a new key.
403	`API_KEY_DISABLED`	The key is disabled.	Enable it or use another key.
403	`CUSTOMER_DISABLED`	The customer account cannot make calls.	Contact account support.
403	`MODEL_NOT_ALLOWED`	The key cannot use the selected model.	Change model or allowed-model settings.
402	`INSUFFICIENT_BALANCE`	The wallet cannot cover the task.	Add funds and submit again.
402	`BILLING_FAILED`	The billing hold or charge failed.	Retry later or contact support.
409	`IDEMPOTENCY_KEY_CONFLICT`	The same key was reused with a different body.	Use a new Idempotency-Key.
429	`RATE_LIMITED`	Request rate exceeded.	Wait and retry with backoff.
429	`CONCURRENT_TASK_LIMIT_EXCEEDED`	Too many tasks are running.	Wait for active tasks to finish.
422	`INVALID_PROMPT`	Prompt or required field validation failed.	Review required fields and limits.
422	`MODEL_MODE_NOT_SUPPORTED`	The model cannot perform this workflow.	Omit model or choose another model.
400 / 422	`1001011026`	File, target size, or task parameter is invalid.	Review request fields and values.
400 / 422	`1001011051`	The file ID does not exist.	Upload again or use a valid file ID.
403	`1001011052`	The file belongs to another account.	Use a file uploaded by this account.
400 / 422	`1001011053`	Unsupported file type.	Use an accepted image or document.
400 / 422	`1001011054`	More than five ordinary input files.	Reduce the number of inputs.
400 / 422	`1001011055`	Decoded file size exceeds the limit.	Compress or resize the file.
500	`1001011056`	File upload or reading failed.	Retry the upload.
404	`1001011019`	Task missing or owned by another account.	Check task_id and API key account.
500	`INTERNAL_ERROR`	FigureLabs platform error.	Retry with backoff; contact support if persistent.

任务最终错误

任务状态	error.code	含义	是否收费？
`failed`	`UPSTREAM_FAILED`	Generation or processing failed.	No
`rejected`	`UPSTREAM_SAFETY_REJECTED`	The safety policy refused the request.	No

速率限制响应头

请求头	含义
`X-RateLimit-Limit`	Current rate limit.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Suggested wait in seconds.
`Retry-After`	How long to wait before retrying.

文件存储错误

HTTP	errorCode	建议操作
413	`STORAGE_QUOTA_EXCEEDED`	Delete files from the console, wait for expiry, or increase the account quota.

资源

模型政策

FigureLabs 和所选模型提供商会对提示词和上传内容进行安全检查。

请求被拒绝时

The task returns status=rejected with a concise reason. Show that reason to your user, let them revise the input, and do not retry the same content automatically.

Rejected tasks are not billed. A technical processing problem returns status=failed, which is also not billed.

面向最终用户的应用

Pass a non-sensitive user reference in safetyIdentifier. Do not send names, email addresses, or other personal data.

资源

llms.txt

为编程智能体提供支持端点、身份验证、任务轮询和错误处理的简明索引。

位置

https://developer.figurelabs.ai/llms.txt

与智能体配合使用

Read https://developer.figurelabs.ai/llms.txt and build a server-side integration that generates a scientific figure, polls the task, and handles rejected requests.

返回快速开始 →