첫 번째 과학 피규어 생성하기
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은 7일간 유효합니다.
"status": "succeeded",
"output_url": "https://files.figurelabs.ai/presigned/...",
"output_type": "image/png",
"actual_price": 80
}
생성 기능
일반적인 이미지 생성·편집 작업은 모두 POST /v1/images/generations를 사용합니다. generations 모드는 프롬프트, 소스 파일, 팔레트, 목표 비율에서 사용자 의도를 추론합니다.
공개 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 필드로 모델을 고정할 수 있습니다. 생략하면 API 키에서 허용되고 워크플로와 비율에 맞는 권장 모델을 FigureLabs가 선택합니다.
| 모델 값 | 표시 이름 | 대략 시간 | 지원 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. |
작업 결과 조회
Generate, Upscale, Vectorize, Flowchart 작업에는 공유 작업 엔드포인트를 사용합니다. 키는 해당 계정 소유 작업만 조회할 수 있습니다.
경로 매개변수
| 매개변수 | 유형 | 필수? | 설명 |
|---|---|---|---|
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.