生成第一張科學圖
只需一個 API 密鑰和兩個請求字段。按照以下步驟提交科學圖、檢查進度並下載結果。
儲存 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
生成任務在後臺運行。首次回應表示任務已被接受,此時尚不包含最終圖像。
{
"task_id": "tsk_01JZ9F7KQ2",
"status": "processing",
"estimated_price": 80,
"currency": "USD"
}
檢查結果
使用返回的 task_id。每隔 2–5 秒檢查一次,直到任務進入最終狀態。
curl https://api.figurelabs.ai/v1/tasks/tsk_01JZ9F7KQ2 \ -H "Authorization: Bearer $FIGURELABS_API_KEY"
下載科學圖
任務成功後,從 output_url 儲存文件。簽名結果 URL 的有效期為七天。
"status": "succeeded",
"output_url": "https://files.figurelabs.ai/presigned/...",
"output_type": "image/png",
"actual_price": 80
}
生成功能
所有常見的圖像生成和編輯任務都使用 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"
}文件上傳與存儲
上傳本地圖像或文檔以獲取 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"
{
"mode": "generations",
"prompt": "Redraw this as a clean publication figure",
"files": ["file_abc123"]
}模型、速度與寬高比
使用可選的 model 字段鎖定模型。省略時,FigureLabs 會選擇 API 密鑰允許且兼容當前工作流和寬高比的推薦模型。
| 模型值 | 顯示名稱 | 大約耗時 | 支援的 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.
- 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.
控制生成結果
基礎生成需要提示詞和工作流。僅在需要更多控制時新增模型、寬高比、風格、配色、格式或會話字段。
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"
}生成與編輯圖像
使用一個端點處理文字生成、草圖和參考圖工作流、圖像增強、局部重繪、重新著色、白色背景和寬高比編輯。
請求參數
| 字段 | 類型 | 是否必填? | 說明 |
|---|---|---|---|
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. |
高清放大圖像
將一張柵格圖放大至 2K、4K 或 8K。任務成功後的輸出格式為 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 |
示例
{
"image_url": "https://example.com/input/source.png",
"target_size": "4k",
"safety_identifier": "user_12345"
}矢量化圖像
將一張柵格圖轉換為可縮放 SVG。V1 每個任務處理一張圖像。
請求參數
| 字段 | 類型 | 是否必填? | 說明 |
|---|---|---|---|
image_url | string / object | 必填 | One bitmap URL, Data URI, file object, or file ID. |
safety_identifier | string | 可選 | Your non-sensitive end-user reference. |
示例
{
"image_url": "https://example.com/input/chart.png"
}生成流程圖
根據提示詞和可選的圖像或文檔輸入建立 SVG 研究流程圖。
請求參數
| 字段 | 類型 | 是否必填? | 說明 |
|---|---|---|---|
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"]
}文件
上傳臨時任務輸入,並在開發者控制檯中管理已上傳文件的元資料。
上傳要求
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. |
查詢任務結果
生成、高清放大、矢量化和流程圖任務共用同一個任務端點。密鑰只能查詢所屬帳戶中的任務。
路徑參數
| 參數 | 類型 | 是否必填? | 說明 |
|---|---|---|---|
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.
成功結果
{
"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 errorAuthentication, balance, permission, or validation failed before task creation. Read the top-level error response.
Task errorA 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.
面向最終使用者的應用
Pass a non-sensitive user reference in safetyIdentifier. Do not send names, email addresses, or other personal data.
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.