Generate your first scientific figure

Generation capabilities

All common image generation and editing tasks use POST /v1/images/generations. The generations mode lets FigureLabs infer the user intent from the prompt, source files, palette, and target ratio.

Public mode values

Capabilities inferred inside generations

Example

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

File uploads and storage

Upload a local image or document to receive a file_id, then pass that ID to a generation or flowchart request. Uploaded files are temporary API inputs, not permanent cloud storage.

Self-serve storage tiers

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.

Enterprise accounts

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.

File validity and deletion

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.

Upload and use a local file

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"]
}

Models, speed & aspect ratios

Use the optional model field to lock a model. If omitted, FigureLabs selects a recommended model allowed by your API key and compatible with the workflow and ratio.

How ratio selection works

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.

Control generated output

A basic generation needs a prompt and workflow. Add model, ratio, style, palette, format, or session fields only when you need more control.

Example

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

Generate & edit images

Use one endpoint for text generation, sketch and reference workflows, enhancement, regional redraw, recoloring, white background, and aspect-ratio editing.

Request parameters

Routing modes

Request examples

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

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

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

Creation response

Upscale an image

Increase one raster image to a 2K, 4K, or 8K target. The successful task output is PNG.

Request parameters

Target tiers & pricing

Example

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

Vectorize an image

Convert one raster image to scalable SVG. V1 processes one image per task.

Request parameters

Example

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

Generate a flowchart

Create an SVG research workflow from a prompt and optional image or document inputs.

Request parameters

Example

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

With a source file

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

Files

Upload temporary task inputs and manage uploaded-file metadata from the developer console.

Upload requirements

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

Form fields

Response fields

Upload example

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"
}

Manage and delete files

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.

Storage-limit errors

Query a task result

Use the shared task endpoint for Generate, Upscale, Vectorize, and Flowchart tasks. A key can query only tasks owned by its account.

Path parameter

Response fields

Polling recommendations

• 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.

Successful result

{
  "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"
}

Failed or rejected tasks

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

Error handling

Handle errors differently depending on whether FigureLabs created a task.

HTTP error format

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

Common HTTP errors

Task terminal errors

Rate-limit response headers

File storage errors

Model policies

FigureLabs and the selected model provider apply safety checks to prompts and uploaded content.

If a request is rejected

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.

For applications with end users

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

llms.txt

Give coding agents a concise index of supported endpoints, authentication, task polling, and error handling.

Location

Use it with an agent

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.