API · MCP · AI agents

Build with the
zfolio API

Generate images and videos across 28+ AI models programmatically. Use the REST API directly or connect through MCP for Claude, Cursor, and other AI tools.

Quick start →MCP setup →

Quick start

Three steps to your first generation. Get an API key, make a request, poll for results.

Step 1

Get an API key

Max 3 active keys per account. Keys are shown once at creation.

Step 2

Generate

POST to /v1/generate with your prompt, models, and aspect ratio. Returns a generation ID immediately.

Credits are deducted upfront. Cost depends on model and resolution.

Step 3

Poll for results

GET /v1/generate/status?ids=... until results complete. Images finish in 5-30s, videos in 30-180s.

MCP handles polling automatically with exponential backoff.

Generate an imagebash

curl -X POST https://api.zfolio.xyz/v1/generate \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Cyberpunk city at sunset, neon reflections on wet streets",
    "mediaType": "image",
    "models": ["gpt-image-2", "gemini-3-pro-image-preview"],
    "aspectRatio": "16:9",
    "resolution": "2K"
  }'

Responsejson

// 202 Accepted
{
  "generationId": "cm2abc123",
  "cost": 16
}

// Then poll:
// GET /v1/generate/status?ids=cm2abc123
{
  "generations": {
    "cm2abc123": {
      "status": "completed",
      "results": [
        {
          "model": "gpt-image-2",
          "status": "completed",
          "imageUrl": "https://r2.zfolio.xyz/gen/abc.png",
          "cost": 4
        },
        {
          "model": "gemini-3-pro-image-preview",
          "status": "completed",
          "imageUrl": "https://r2.zfolio.xyz/gen/def.png",
          "cost": 12
        }
      ]
    }
  }
}

Authentication

All requests require a bearer token. Create API keys from your zfolio dashboard.

Authorization headerhttp

Authorization: Bearer sk_live_<key>

Key format

sk_live_ prefix on mainnet
sk_test_ prefix on Base Sepolia testnet
64-character Base62 random suffix
Hashed on storage, shown once at creation
Max 3 active keys per account

Rate limits

Tier	Generate	Batch	Poll
Free	5/min	25/min	50/min
Creator	15/min	75/min	150/min
Pro	30/min	150/min	300/min

Rate-limited responses return 429 with a Retry-After header.

MCP server

Connect zfolio to Claude, Cursor, or any MCP-compatible AI tool. The server handles polling, auth, and result formatting.

claude_desktop_config.jsonjson

{
  "mcpServers": {
    "zfolio": {
      "command": "npx",
      "args": ["-y", "@zfolio/mcp"],
      "env": {
        "ZFOLIO_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

5 tools available

generate_imageGenerate images across multiple models
generate_videoGenerate videos with duration control
get_generationCheck status of a previous generation
list_modelsGet available models and capabilities
get_balanceCheck credit balance and membership tier

Example prompt

“Generate a cyberpunk portrait using GPT Image 2 and Seedream 4.5 at 16:9, 2K resolution”

API reference

Base URL: https://api.zfolio.xyz/v1

POST/v1/generate

Submit a multi-model generation request. Returns immediately with a generation ID. Poll /v1/generate/status for results.

Param	Type	Required	Description
prompt	string	Yes	1-10,000 characters
mediaType	"image" \| "video"	Yes	Generation type
models	string[]	Yes	1-6 model IDs
aspectRatio	string	Yes	e.g. "1:1", "16:9", "9:16"
resolution	string	No	"0.5K", "1K", "2K", "4K" (image) or "480p", "720p", "1080p" (video)
duration	number	No	Seconds. Required for video models.
referenceImageUrls	string[]	No	Up to 8 uploaded reference images
stylePassIds	string[]	No	Style pass IDs to apply
templateId	string	No	Prompt template ID

202 Accepted·400 Invalid input·402 Insufficient credits

GET/v1/generate/status

Poll generation results. Supports batch polling up to 50 IDs.

Param	Type	Required	Description
ids	string	Yes	Comma-separated generation IDs, max 50

Result statuses

pendingprocessingcompletedfailed

GET/v1/balance

Returns current credit balance and membership tier.

Responsejson

{
  "creditBalance": 2450,
  "membershipTier": "creator"
}

Other endpoints

Method	Path	Description
GET	/v1/history	Paginated generation history
GET	/v1/transactions	Credit transaction ledger
GET	/v1/payments	Payment history
GET	/v1/passes	Browse style passes (paginated, filterable)
POST	/v1/passes	Create a style pass
GET	/v1/templates	Browse prompt templates (paginated)
POST	/v1/templates	Create a prompt template
POST	/v1/studio/reserve	Reserve credits for batch workflow
POST	/v1/studio/settle	Settle reserve, refund unused credits
POST	/v1/upload-image	Upload reference image for generation
GET	/v1/download	Download generation result
GET	/v1/profile/analytics	Creator analytics (7d/30d)
GET	/v1/profile/earnings	Royalty earnings summary
GET	/v1/workflows	List saved Studio workflows
POST	/v1/workflows	Save a workflow
POST	/v1/api-keys	Create a new API key
GET	/v1/api-keys	List your API keys (prefixes only)
DELETE	/v1/api-keys/:id	Revoke an API key

Models

12 image models and 15 video models. Use list_models via MCP or browse below.

Image models

Model	ID	Cost	Resolutions	Ref images
GPT Image 2	gpt-image-2	2-6 cr	1K, 2K, 4K	Up to 16
Imagen 4.0	imagen-4.0-apimart	12 cr	-	-
Nano Banana Pro	gemini-3-pro-image-preview	12-15 cr	1K, 2K, 4K	Up to 14
Nano Banana 2	gemini-3.1-flash-image-preview	9-18 cr	0.5K-4K	Up to 14
Seedream 4.5	doubao-seedream-4.5	8 cr	2K, 4K	Up to 10
Seedream 5 Lite	doubao-seedream-5-0-lite	8 cr	2K	Up to 10
Grok Imagine	grok-imagine-1.0-apimart	5 cr	-	-
Qwen Image 2	qwen-image-2.0	6 cr	1K, 2K	Up to 4
Wan 2.7	wan2.7-image	7 cr	1K, 2K	Up to 9
Nano Banana	gemini-2.5-flash-image-preview	4 cr	1K	Up to 14
Z-Image Turbo	z-image-turbo	3 cr	1K, 2K	-
Seedream 4.0	doubao-seedance-4-0	6 cr	1K, 2K, 4K	Up to 10

Video models

Model	ID	Cost	Durations
VEO3 Quality	veo3.1-quality	180 (8s) cr	8s
VEO3 Fast	veo3.1-fast	24 (8s) cr	8s
Sora 2	sora-2-preview	8 (any) cr	4s, 8s, 12s
Kling v3	kling-v3	101-303 cr	5s, 10s, 15s
Kling O1	kling-video-o1	101-202 cr	5s, 10s
Seedance 2.0	doubao-seedance-2.0	109-327 cr	5s, 10s, 15s
Hailuo 02	minimax-hailuo-02	30 cr	5s, 10s
Wan 2.7	wan2.7	100-299 cr	5s, 10s, 15s
Vidu Q3 Pro	viduq3-pro	144-576 cr	4s, 8s, 16s
SkyReels V4	skyreels-v4-fast	132-396 cr	5s, 10s, 15s
Grok Video	grok-imagine-1.0-video-apimart	13-21 cr	6s, 10s
Kling 2.6	kling-v2-6	56-111 cr	5s, 10s
Seedance 1.5	doubao-seedance-1-5-pro	66-132 cr	5s, 10s
Wan 2.5	wan2.5-preview	100-200 cr	5s, 10s
Vidu Q3 Turbo	viduq3-turbo	58-231 cr	4s, 8s, 16s
VEO3 Lite	veo3.1-lite	12 (8s) cr	8s

Errors & status codes

All errors return a JSON object with an error field containing a human-readable message.

Error responsejson

{
  "error": "Insufficient credits. Need 24, have 12."
}

Code	Meaning
200	Success
201	Created
202	Accepted (generation queued)
400	Invalid input
401	Missing or invalid API key
402	Insufficient credits
404	Not found
429	Rate limited (check Retry-After header)
500	Server error

Credits & pricing

1 credit = $0.01 USD. Buy credits at zfolio.xyz/pricing.

Starter1,000credits

Creator3,000credits

$24

Pro6,000credits

$40

Payments settle on Base via x402 (USDC). No cards, no chargebacks.

Build with thezfolio API