API Overview & Quickstart

Architecture overview

Every public model on Wizzx shares one production gateway (https://api.wizzx.ai), one API key, and one asynchronous task lifecycle:

Discover public models and live credit tiers via GET /pricing or GET /v1/models (no authentication required).
Submit a generation job to POST /api/v1/task/submit/{model_key} (or POST /api/v1/music/{action} for Suno) with an optional Idempotency-Key header.
Poll GET /api/v1/task/{task_id} (or POST /api/v1/task/status) until status reaches SUCCEEDED or FAILED.

New accounts receive 200 free credits ($0.20 USD) after sign-in (1,000 credits = 1.00 USD). Generate or rotate your key anytime in the API Keys dashboard.

Authentication

Pass your Wizzx API key in the HTTP Authorization header on every authenticated request:

Authorization: Bearer wzk_live_...

Keep keys in environment variables (WIZZX_API_KEY) rather than client-side bundles or source control. Public discovery endpoints (GET /pricing, GET /v1/models, and GET /pricing/metrics) do not require authentication and include browser CORS headers.

60-second quickstart

1. Submit an image task

curl --fail-with-body --silent --show-error \
  -X POST "https://api.wizzx.ai/api/v1/task/submit/nano-banana-2" \
  -H "Authorization: Bearer $WIZZX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-001" \
  --data '{
    "prompt": "Studio product shot of an anodized aluminum camera on warm slate, soft rim lighting",
    "aspect_ratio": "16:9",
    "resolution": "1K",
    "output_format": "jpg"
  }'

The gateway validates parameters and atomically reserves credits before queuing the job:

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "4bbbc9e0-8de8-4f35-a31e-8596c1a6d18a",
    "model_key": "nano-banana-2",
    "credits_deducted": 48
  },
  "request_id": "d54c66a8-0f0f-439c-bd3a-36f3fd275881"
}

2. Poll the task by ID

curl --fail-with-body --silent --show-error \
  "https://api.wizzx.ai/api/v1/task/4bbbc9e0-8de8-4f35-a31e-8596c1a6d18a" \
  -H "Authorization: Bearer $WIZZX_API_KEY"

When data.status reaches SUCCEEDED, read your generated asset URLs from data.result_urls (and data.result for Suno music actions). If a task fails upstream, reserved credits are automatically refunded and data.credits_deducted reports 0.

Discovery & AI agent entrypoints

Entrypoint	Purpose
`GET https://api.wizzx.ai/pricing`	Live public model catalog, billing units, and credit tiers (`?locale=zh` for Simplified Chinese notes).
`GET https://api.wizzx.ai/v1/models`	Public model list discovery endpoint (`data.object: "list"`, `data.models`) with embedded Wizzx pricing metadata.
`GET https://api.wizzx.ai/pricing/metrics`	Rolling 24-hour settled success rate and average latency per public model.
`https://docs.wizzx.ai/api-reference/openapi.json`	Complete OpenAPI 3.1 specification for SDKs, validators, and agent tools.
`https://docs.wizzx.ai/llms.txt` & `https://wizzx.ai/llms.txt`	Compact Markdown indexes for Claude Code, Codex, Cursor, and MCP agents.

Generate Media with AI Agents

Copy a deterministic execution contract for Claude Code, Codex, or custom agent skills.

Error Codes & Idempotency

Handle 402 credit shortfalls, 409 idempotency locks, and 429 Retry-After headers safely.

Getting started

Agent integrations

Video Generation

Image Generation

Audio Generation

API Overview & Quickstart

Architecture overview

Authentication

60-second quickstart

1. Submit an image task

2. Poll the task by ID

Discovery & AI agent entrypoints

Generate Media with AI Agents

Error Codes & Idempotency