Complete guide to the AutoFigureEdit Open API for automated figure editing and image generation

Getting Started

The AutoFigureEdit Open API provides programmatic access to our auto figure edit capabilities through two distinct generation modes: Standard (converting text or images into new images) and Pipeline (an AI-driven workflow purpose-built for scientific figures and illustrations).

Base URL

https://open.autofigureedit.com/api/v1

HTTPS is mandatory for all API communication.

Authentication

Only Team plan subscribers (Team Basic or Team Pro) can access the API. Generate your team API keys through the team settings panel.

Include a Bearer token in the Authorization header with every request:

curl -H "Authorization: Bearer sk-team-your-api-key" \
  https://open.autofigureedit.com/api/v1/credits

Team API keys always carry the sk-team- prefix. Legacy personal keys (sk-) are no longer valid for API calls.

Team Plans

The AutoFigureEdit API is bundled exclusively with Team subscriptions:

Plan	Price	Credits	API Keys	Rate Limit
Team Basic	$999/year	12,000/year	Up to 3	120 RPM
Team Pro	$1,499/year	24,000/year	Up to 10	300 RPM

The entire team draws from a single credit pool. API calls are billed at standard rates without resolution-based discounts.
When team members use the AutoFigureEdit web interface, they consume credits from the shared pool but benefit from plan-tier pricing advantages.

Rate Limiting

The auto figure edit API enforces three tiers of throttling:

Layer	Limit	Scope
IP-based	120 requests/min	Per client IP (evaluated before auth)
Key-based	60 requests/min	Per individual API key
Team-based	120 or 300 requests/min	Per team account (Basic: 120, Pro: 300)

Exceeding any threshold triggers a 429 response that includes a Retry-After header indicating when to retry.

Request Limits

Constraint	Limit
Request body size	1 MB max
`Content-Length` header	Required for POST requests
`prompt` length	10,000 characters
`options.content` length	100,000 characters
`options.image_input` items	10 max

Endpoints

Check Credits

Retrieves how many credits remain in your team account.

GET /api/v1/credits

Response

{
  "success": true,
  "data": {
    "remaining_credits": 450
  }
}

Generate Image

Initiates an asynchronous image generation job through AutoFigureEdit. Once submitted, use the Query Task endpoint to monitor progress and retrieve results.

POST /api/v1/generate

Common Parameters

Parameter	Type	Required	Description
`type`	string	Yes	`"standard"` or `"pipeline"`
`scene`	string	Yes	`"text-to-image"` or `"image-to-image"`
`prompt`	string	Conditional	Text description of the image you want to create
`model`	string	Conditional	Target model name (Standard mode only)
`options`	object	No	Additional configuration (detailed below)

Standard Mode

Leverages Kie/Fal providers for versatile, general-purpose auto figure edit and image generation tasks.

Parameter	Type	Required	Description
`model`	string	Yes	`"nano-banana-pro"` or `"nano-banana-2"`
`prompt`	string	Yes	Text prompt
`options.resolution`	string	No	`"1K"` (default), `"2K"`, or `"4K"`
`options.aspect_ratio`	string	No	Aspect ratio, default `"auto"`
`options.output_format`	string	No	`"png"` (default), `"jpg"`, `"jpeg"`, `"webp"`
`options.image_input`	string[]	image-to-image	Array of source image URLs (HTTPS only, max 10)
`options.google_search`	boolean	No	Enable Google search (nano-banana-2 only)

Restrictions on image URLs: Every URL in image_input must begin with https://. Private or internal network addresses and non-standard ports are blocked.

Example: Standard text-to-image

curl -X POST https://open.autofigureedit.com/api/v1/generate \
  -H "Authorization: Bearer sk-team-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "standard",
    "scene": "text-to-image",
    "prompt": "A futuristic city skyline at sunset",
    "model": "nano-banana-pro",
    "options": {
      "resolution": "2K",
      "output_format": "png"
    }
  }'

Example: Standard image-to-image

curl -X POST https://open.autofigureedit.com/api/v1/generate \
  -H "Authorization: Bearer sk-team-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "standard",
    "scene": "image-to-image",
    "prompt": "Make this more professional",
    "model": "nano-banana-2",
    "options": {
      "image_input": ["https://example.com/source.png"],
      "resolution": "1K"
    }
  }'

Pipeline Mode

Harnesses the DeepScience multi-stage pipeline to produce AI-generated scientific visuals -- diagrams, plots, and technical illustrations suitable for academic publications.

Parameter	Type	Required	Description
`prompt`	string	text-to-image	Text prompt
`options.content`	string	Yes	Source paper text or contextual material that guides the pipeline
`options.task_name`	string	No	`"diagram"` (default) or `"plot"`
`options.resolution`	string	No	`"1K"` (default), `"2K"`, or `"4K"`
`options.output_format`	string	No	`"png"` (default), `"jpg"`, `"jpeg"`, `"webp"`
`options.image_input`	string[]	image-to-image	Array of source image URLs (HTTPS only, max 10)

Restrictions on image URLs: Identical rules as Standard mode -- only HTTPS, no private IPs, no non-standard ports.

A Basic or Pro subscription is required for Pipeline mode.

Example: Pipeline text-to-image

curl -X POST https://open.autofigureedit.com/api/v1/generate \
  -H "Authorization: Bearer sk-team-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pipeline",
    "scene": "text-to-image",
    "prompt": "Architecture diagram for transformer model",
    "options": {
      "content": "This paper presents a novel transformer architecture with multi-head attention...",
      "task_name": "diagram",
      "resolution": "2K"
    }
  }'

Example: Pipeline image-to-image

curl -X POST https://open.autofigureedit.com/api/v1/generate \
  -H "Authorization: Bearer sk-team-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "pipeline",
    "scene": "image-to-image",
    "options": {
      "content": "This paper presents a novel transformer architecture...",
      "image_input": ["https://example.com/my-diagram.png"],
      "resolution": "2K"
    }
  }'

Generate Response

{
  "success": true,
  "data": {
    "task_id": "7655ed66-3a83-4a5a-9cb1-3b7c449ec4a9",
    "status": "pending",
    "cost_credits": 20
  }
}

List Tasks

Fetches a paginated overview of your generation tasks. You can narrow results by status.

GET /api/v1/tasks

Query Parameters

Parameter	Type	Required	Description
`page`	number	No	Page number, default `1`
`limit`	number	No	Items per page, default `20`, max `100`
`status`	string	No	Filter by status: `"pending"`, `"processing"`, `"success"`, `"failed"`, or `"canceled"`

Response

{
  "success": true,
  "data": {
    "tasks": [
      {
        "task_id": "7655ed66-3a83-4a5a-9cb1-3b7c449ec4a9",
        "type": "standard",
        "model": "nano-banana-pro",
        "scene": "text-to-image",
        "status": "success",
        "cost_credits": 10,
        "created_at": "2026-03-12T06:57:48.067Z",
        "output": {
          "images": [
            {
              "url": "https://storage.autofigureedit.com/uploads/...",
              "type": "image/png"
            }
          ]
        },
        "error": null
      }
    ],
    "pagination": {
      "total": 42,
      "page": 1,
      "limit": 20,
      "total_pages": 3
    }
  }
}

Example

# List all tasks (page 1)
curl -H "Authorization: Bearer sk-team-your-api-key" \
  "https://open.autofigureedit.com/api/v1/tasks"

# Filter by status with pagination
curl -H "Authorization: Bearer sk-team-your-api-key" \
  "https://open.autofigureedit.com/api/v1/tasks?status=success&page=2&limit=10"

Query Task

Checks the current state of a generation job. Continue polling until status reaches "success", "failed", or "canceled".

GET /api/v1/task/:taskId

Response (processing)

{
  "success": true,
  "data": {
    "task_id": "7655ed66-...",
    "type": "pipeline",
    "model": "pipeline",
    "scene": "text-to-image",
    "status": "processing",
    "cost_credits": 14,
    "created_at": "2026-03-12T06:57:48.067Z",
    "output": {
      "images": [],
      "current_stage": "stylist"
    },
    "error": null
  }
}

For Pipeline jobs, the current_stage field reveals which processing step is active at that moment (possible values include retriever, planner, stylist, visualizer, critic_round_0, among others).

Response (completed)

{
  "success": true,
  "data": {
    "task_id": "7655ed66-...",
    "type": "standard",
    "model": "nano-banana-pro",
    "scene": "text-to-image",
    "status": "success",
    "cost_credits": 14,
    "created_at": "2026-03-12T06:57:48.067Z",
    "output": {
      "images": [
        {
          "url": "https://storage.autofigureedit.com/uploads/...",
          "type": "image/png"
        }
      ]
    },
    "error": null
  }
}

Response (failed)

{
  "success": true,
  "data": {
    "task_id": "7655ed66-...",
    "type": "standard",
    "model": "nano-banana-pro",
    "scene": "text-to-image",
    "status": "failed",
    "cost_credits": 0,
    "created_at": "2026-03-12T06:57:48.067Z",
    "output": {
      "images": []
    },
    "error": "task failed"
  }
}

Credit Costs

Your credits are deducted only upon successful task completion. The amount charged varies based on generation mode, selected model, output resolution, and subscription tier.

Standard Mode

Model	1K	2K	4K
nano-banana-pro	10	20	40
nano-banana-2	5	10	20

Pipeline Mode

Starts at 6 credits for 1K resolution with default processing steps.

Resolution	Multiplier
1K	x1
2K	x2
4K	x4

Plan Discounts (Web Only)

Subscribers on higher-tier plans enjoy reduced rates for high-resolution output when working through the web interface. All API requests are charged at the base rate with no resolution discounts applied.

Plan	Standard 2K	Standard 4K	Pipeline 2K	Pipeline 4K
Hobby	Full price	Full price	Full price	Full price
Basic	Same as 1K	50% off	Same as 1K	50% off
Pro	Same as 1K	Same as 1K	Same as 1K	Same as 1K
Team (API)	Full price	Full price	Full price	Full price

Errors

Every error response from the AutoFigureEdit API uses a consistent structure:

{
  "success": false,
  "error": {
    "message": "error description"
  }
}

HTTP Status	Description
400	Bad request -- parameters are missing or malformed
401	Unauthorized -- API key is invalid or absent
402	Payment required -- your credit balance is too low
403	Forbidden -- API access is restricted to Team plans (personal `sk-` keys are rejected)
404	Not found -- the specified task does not exist or belongs to a different account
411	Length required -- POST requests must include a `Content-Length` header
413	Payload too large -- the request body exceeds the 1 MB limit
429	Too many requests -- you have hit a rate limit
500	Internal server error
503	Service unavailable -- an upstream provider is temporarily down

Quick Start

Below is a full working example that submits an auto figure edit generation request and waits for the finished result:

API_KEY="sk-team-your-api-key"
BASE_URL="https://open.autofigureedit.com/api/v1"

# 1. Check your credits
curl -s -H "Authorization: Bearer $API_KEY" "$BASE_URL/credits"

# 2. Create a generation task
RESPONSE=$(curl -s -X POST "$BASE_URL/generate" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "standard",
    "scene": "text-to-image",
    "prompt": "A red apple on a white background",
    "model": "nano-banana-pro"
  }')

echo "$RESPONSE"
TASK_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['task_id'])")

# 3. Poll until complete
while true; do
  RESULT=$(curl -s -H "Authorization: Bearer $API_KEY" "$BASE_URL/task/$TASK_ID")
  STATUS=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['status'])")
  echo "Status: $STATUS"
  if [ "$STATUS" = "success" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "canceled" ]; then
    echo "$RESULT" | python3 -m json.tool
    break
  fi
  sleep 5
done

API Reference

Getting Started

Authentication

Team Plans

Rate Limiting

Request Limits

Endpoints

Check Credits

Generate Image

Common Parameters

Standard Mode

Pipeline Mode

Generate Response

List Tasks

Query Task

Credit Costs

Standard Mode

Pipeline Mode

Plan Discounts (Web Only)

Errors

Quick Start

On this page