5 分鐘快速開始

生成第一張科學圖

只需一個 API 密鑰和兩個請求字段。按照以下步驟提交科學圖、檢查進度並下載結果。

1為錢包充值通過 Stripe 至少充值 $10。
2建立 API 密鑰密鑰顯示後請立即複製,只會顯示一次。
3使用伺服器或終端切勿在瀏覽器程式碼中暴露密鑰。
1

儲存 API 密鑰

將 fl_live_... 替換為控制檯中的密鑰。使用環境變量可避免將密鑰寫入程式碼。

export FIGURELABS_API_KEY="fl_live_..."
2

提交生成請求

這個最簡請求會讓 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 時,這也是預設值。

3

儲存任務 ID

生成任務在後臺運行。首次回應表示任務已被接受,此時尚不包含最終圖像。

HTTP/1.1 202 Accepted
{
  "task_id": "tsk_01JZ9F7KQ2",
  "status": "processing",
  "estimated_price": 80,
  "currency": "USD"
}
價格字段以美分為單位。 80 表示 $0.80,而不是 $80。
4

檢查結果

使用返回的 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。此任務不會收費。
5

下載科學圖

任務成功後,從 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適用場景必需輸入
generationsText 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_redrawForce the regional-redraw processing path.Prompt, original image, and one mask.
white_backgroundForce 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-up0 GB
More than $0 and up to $101 GB
More than $10 and up to $502 GB
More than $50 and below $2005 GB
$200 or more20 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-previewNano Banana Pro~30 sec16:9, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 21:9
nano-banana-2Nano Banana 2~30 sec16:9, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 21:9
gpt-image-2GPT Image 2~90 sec16:9, 1:1, 2:3, 3:2, 4:5, 5:4, 9:16
nano-bananaNano Banana~15 sec16:9, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 21:9
gpt-image-1GPT Image 1.5~90 sec3:2, 1:1, 2:3
seedream-5-0-260128Seedream 5.0 Lite~120 sec16:9, 1:1, 2:3, 3:4, 9:16, 3:2, 4:3, 21:9
seedream-4-5-251128Seedream 4.5~30 sec16:9, 1:1, 2:3, 3:4, 9:16, 3:2, 4:3, 21:9
flux-kontext-maxFlux.2 Max~15 sec4:3, 1:1, 16:9, 9:16, 21:9, 2:3, 5:1, 3:2, 3:7, 7:3
sora-imageSora~90 sec3: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.

請求參數

字段類型是否必填?說明
modelstring可選Model value from Models & ratios. Omit for recommended routing.
promptstringConditionalMaximum 2,000 characters. Required for generation and instruction-driven edits.
sessionIdstring可選Continue an existing session; a new session is created when omitted.
modestring可選Routing mode. Default: generations. Other values: region_redraw and white_background.
stylestring可選Flat, 3D, 2.5D, hand_drawn, or line_art. Default: Flat.
colorPalettestring可選1–8 comma-separated #RRGGBB colors used as visual guidance.
imageUrlstring / object / array可選Legacy-compatible reference input: URL, Data URI, file object, file ID, or array.
filesstring / object / array可選Image or document inputs. Merged with imageUrl.
maskstring / objectConditionalOne image; required and only valid for region_redraw.
targetRatiostringConditionalOptional ratio such as 16:9. Omit it to let FigureLabs choose a suitable ratio for the generation task.
formatstring可選png (default) or vector. Vector runs generation plus SVG conversion.
qualitystring可選V1 supports only high; default high; no price change.
quoteMessageIdnumber可選Message to edit. Requires sessionId; otherwise ignored.
safetyIdentifierstring可選Your non-sensitive end-user reference for safety auditing.

路由模式

mode行為輸入要求
generationsAgent automatically identifies text, sketch, reference, enhance, recolor, or aspect-ratio intent.Prompt and/or source files. Default when omitted.
region_redrawFixed regional-redraw processing.Prompt, original image, and one mask.
white_backgroundFixed 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_idstringSave this ID and query Tasks.
session_idstringUse it to continue the same session.
statusstringUsually processing.
estimated_pricenumberEstimated hold in USD cents.
currencystringUSD in V1.
API 參考

高清放大圖像

將一張柵格圖放大至 2K、4K 或 8K。任務成功後的輸出格式為 PNG。

POST/v1/images/upscale202 Accepted
InputFirst valid bitmap image
Target2K, 4K, or 8K
Outputimage/png

請求參數

字段類型是否必填?說明
image_urlstring / object / array必填URL, Data URI, file object, or file ID. If an array is sent, the first valid image is used.
target_sizestring可選2k, 4k, 8k, or width x height such as 4096x2048. Default: 2K tier.
safety_identifierstring可選Your non-sensitive end-user reference.

目標等級與價格

值目標長邊標準價格
2k or omittedApproximately 2,048 px$0.02
4kApproximately 4,096 px$0.04
8kApproximately 8,192 px$0.08
4096x2048Larger 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_urlstring / object必填One bitmap URL, Data URI, file object, or file ID.
safety_identifierstring可選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

請求參數

字段類型是否必填?說明
promptstring必填Non-empty flowchart instruction.
session_idstring可選Continue an existing session; creates a new session when omitted.
ratiostring可選Output ratio such as 16:9 or 1:1.
file_urlstring / object / array可選Legacy single-file field; also accepts file object, file ID, or array.
filesstring / 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.

表單字段

字段類型是否必填?說明
filefile必填Image or document. Video and audio are not supported.
purposestring可選general, image_generation, flowchart, or mask. Default: general.

回應字段

字段說明
idFile ID to pass to a task request.
file_name, mime_type, sizeUploaded-file metadata.
created_at, expires_atUTC 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.

存儲限額錯誤

HTTPerrorCode含義
413STORAGE_QUOTA_EXCEEDEDThe 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_idstring必填ID returned by a task creation endpoint; usually starts with tsk_.

回應字段

字段類型說明
task_idstringTask ID.
session_idstringSession ID for follow-up generation.
statusstringpending, processing, succeeded, failed, rejected, or canceled.
output_urlstring / nullSeven-day signed result URL after success.
output_typestring / nullFor example image/png, image/svg+xml, png, or svg.
errorobject / nullError details for failed or rejected tasks.
error.codestringPublic task error code.
error.messagestringHuman-readable task error.
actual_pricenumber / nullFinal charge in USD cents after success.
estimated_pricenumber / nullEstimated hold in USD cents.
currencystring / nullUSD in V1.
created_atstring / nullUTC RFC 3339 time, ending in Z.
finished_atstring / nullCompletion 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 錯誤

HTTPerrorCode具體含義建議操作
401INVALID_API_KEYKey missing, malformed, or unknown.Check the Authorization header.
401API_KEY_REVOKEDThe key was permanently revoked.Create and use a new key.
403API_KEY_DISABLEDThe key is disabled.Enable it or use another key.
403CUSTOMER_DISABLEDThe customer account cannot make calls.Contact account support.
403MODEL_NOT_ALLOWEDThe key cannot use the selected model.Change model or allowed-model settings.
402INSUFFICIENT_BALANCEThe wallet cannot cover the task.Add funds and submit again.
402BILLING_FAILEDThe billing hold or charge failed.Retry later or contact support.
409IDEMPOTENCY_KEY_CONFLICTThe same key was reused with a different body.Use a new Idempotency-Key.
429RATE_LIMITEDRequest rate exceeded.Wait and retry with backoff.
429CONCURRENT_TASK_LIMIT_EXCEEDEDToo many tasks are running.Wait for active tasks to finish.
422INVALID_PROMPTPrompt or required field validation failed.Review required fields and limits.
422MODEL_MODE_NOT_SUPPORTEDThe model cannot perform this workflow.Omit model or choose another model.
400 / 4221001011026File, target size, or task parameter is invalid.Review request fields and values.
400 / 4221001011051The file ID does not exist.Upload again or use a valid file ID.
4031001011052The file belongs to another account.Use a file uploaded by this account.
400 / 4221001011053Unsupported file type.Use an accepted image or document.
400 / 4221001011054More than five ordinary input files.Reduce the number of inputs.
400 / 4221001011055Decoded file size exceeds the limit.Compress or resize the file.
5001001011056File upload or reading failed.Retry the upload.
4041001011019Task missing or owned by another account.Check task_id and API key account.
500INTERNAL_ERRORFigureLabs platform error.Retry with backoff; contact support if persistent.

任務最終錯誤

任務狀態error.code含義是否收費?
failedUPSTREAM_FAILEDGeneration or processing failed.No
rejectedUPSTREAM_SAFETY_REJECTEDThe safety policy refused the request.No

速率限制回應頭

請求頭含義
X-RateLimit-LimitCurrent rate limit.
X-RateLimit-RemainingRequests remaining in the current window.
X-RateLimit-ResetSuggested wait in seconds.
Retry-AfterHow long to wait before retrying.

文件存儲錯誤

HTTPerrorCode建議操作
413STORAGE_QUOTA_EXCEEDEDDelete 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.
返回快速開始 →