5분 퀵스타트

첫 번째 과학 피규어 생성하기

API 키와 두 개의 요청 필드만 있으면 됩니다. 피규어를 제출하고, 진행 상황을 확인한 뒤 결과를 다운로드하세요.

1지갑 충전Stripe로 최소 $10을 추가하세요.
2API 키 만들기표시되면 바로 복사하세요. 한 번만 표시됩니다.
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은 $80이 아니라 $0.80을 의미합니다.
4

결과 확인

반환된 task_id를 사용하세요. 상태가 최종이 될 때까지 2–5초마다 확인하세요.

curl https://api.figurelabs.ai/v1/tasks/tsk_01JZ9F7KQ2 \
  -H "Authorization: Bearer $FIGURELABS_API_KEY"
pending / processing기다렸다가 다시 확인하세요.
succeededoutput_url을 다운로드하세요.
failed / rejectederror를 확인하세요. 과금되지 않습니다.
5

피규어 다운로드

작업이 성공하면 output_url에서 파일을 저장하세요. 서명된 결과 URL은 7일간 유효합니다.

{
  "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 모드는 프롬프트, 소스 파일, 팔레트, 목표 비율에서 사용자 의도를 추론합니다.

공개 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 필드로 모델을 고정할 수 있습니다. 생략하면 API 키에서 허용되고 워크플로와 비율에 맞는 권장 모델을 FigureLabs가 선택합니다.

첫 통합에서는: 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 레퍼런스

작업 결과 조회

Generate, Upscale, Vectorize, Flowchart 작업에는 공유 작업 엔드포인트를 사용합니다. 키는 해당 계정 소유 작업만 조회할 수 있습니다.

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.
퀵스타트로 돌아가기 ↑