# Pixola REST API > HTTP API for programmatic access to 40+ AI image generation models. > Base URL: https://www.pixola.ai/api/v1 > Docs: https://www.pixola.ai/docs/api ## Authentication All requests require a Bearer token. Create API keys at https://www.pixola.ai/settings. Authorization: Bearer pxk_YOUR_API_KEY ## Endpoints ### GET /api/v1/models List all available AI models with slugs, descriptions, and credit pricing. No authentication required. ### GET /api/v1/models/{model} Get detailed info for a single model (e.g. /models/flux-2). Requires authentication. Response: { slug, name, bestFor, description, tags, released, pricing, researcher, researcherUrl, urls, samplePrompts } ### GET /api/v1/styles List all style presets organized by category (watercolor, anime, art-deco, etc.). No authentication required. ### GET /api/v1/styles/{style} Get details for a single style preset (e.g. /styles/watercolor). Requires authentication. Response: { slug, name, category, prompt, alias, image } ### GET /api/v1/shapes List all aspect ratio options with slugs and dimensions. No authentication required. ### GET /api/v1/shapes/{shape} Get details for a single shape (e.g. /shapes/landscape-wide). Requires authentication. Response: { slug, name, aspectRatio } ### GET /api/v1/credits Returns your credit balance and current subscription plan. Requires authentication. ### POST /api/v1/generate Submit an image generation request. Returns immediately with a batchId. Poll GET /api/v1/batches/{batchId} for results. Requires authentication. Request body (JSON): - prompt (string, required) — the image generation prompt - model (string, optional) — model slug, e.g. "flux-2", "gpt-image-1.5". Defaults to platform default. - style (string, optional) — style preset slug, e.g. "watercolor", "anime". Defaults to "no-style". - shape (string, optional) — aspect ratio slug, e.g. "square", "landscape-wide". Defaults to "square". - quality (string, optional) — "standard" or "hd". HD uses more credits. Response: { batchId: string } ### GET /api/v1/batches List your generation batches, newest first. Supports cursor-based pagination. Requires authentication. Query parameters: - limit (number, optional) — max batches per page, default 20, max 100 - cursor (number, optional) — pass the nextCursor value from a previous response to fetch the next page Response: { batches: [{ batchId, status, prompt, quality, imageCount, createdAt }], nextCursor: integer | null, hasMore: boolean } ### GET /api/v1/batches/{batchId} Check the status of a generation batch. Requires authentication. Response: { batchId, status, images: [{ imageId, url, model, status, creditsCharged }] } Status values: processing | complete | failed | rejected ### GET /api/v1/images List your generated images, newest first. Supports cursor-based pagination. Requires authentication. Query parameters: - limit (number, optional) — max images per page, default 50, max 100 - cursor (integer, optional) — pass the nextCursor value from a previous response to fetch the next page - batchId (string, optional) — filter images to a specific batch Response: { images: [...], nextCursor: integer | null, hasMore: boolean } Each image: { imageId, batchId, url, title, model, status, createdAt, creditsCharged, isFavorite } Pagination example: # First page GET /api/v1/images?limit=20 # Next page (use nextCursor from previous response) GET /api/v1/images?limit=20&cursor=1771393474019 ### GET /api/v1/images/{imageId} Get full details for a specific image. Requires authentication. Response: { imageId, batchId, url, title, prompt, model, status, createdAt, creditsCharged } ## OpenAPI Spec Machine-readable OpenAPI 3.0 spec: GET https://www.pixola.ai/api/v1/openapi.json Import into Postman, Insomnia, or any OpenAPI-compatible tool. ## Rate Limits - 30 requests per minute per API key - 1,000 requests per day per API key - Exceeded limit returns HTTP 429 with Retry-After header ## Error Codes Status | Code | Description -------|----------------------|------------------------------ 400 | bad_request | Invalid parameters 401 | unauthorized | Missing or invalid API key 404 | not_found | Resource not found 409 | content_flagged | Prompt flagged by moderation 409 | insufficient_credits | Not enough credits 429 | rate_limited | Too many requests 500 | internal_error | Server error Error response format: { error: { code: string, message: string } } ## Quick Start Example # Submit a generation curl -X POST https://www.pixola.ai/api/v1/generate \ -H "Authorization: Bearer pxk_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt": "A serene mountain lake at golden hour", "model": "flux-2", "quality": "hd"}' # Response: {"batchId": "abc123..."} # Poll for results curl https://www.pixola.ai/api/v1/batches/abc123 \ -H "Authorization: Bearer pxk_YOUR_API_KEY" ## Python Example import requests, time headers = {"Authorization": "Bearer pxk_YOUR_API_KEY"} res = requests.post( "https://www.pixola.ai/api/v1/generate", headers=headers, json={"prompt": "A cyberpunk cityscape", "model": "flux-2", "quality": "hd"}, ) batch_id = res.json()["batchId"] while True: time.sleep(2) batch = requests.get( f"https://www.pixola.ai/api/v1/batches/{batch_id}", headers=headers, ).json() if batch["status"] in ("complete", "failed", "rejected"): break print(batch["images"][0]["url"]) ## JavaScript Example const res = await fetch("https://www.pixola.ai/api/v1/generate", { method: "POST", headers: { "Authorization": "Bearer pxk_YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ prompt: "A cyberpunk cityscape", model: "flux-2", quality: "hd" }), }); const { batchId } = await res.json(); let batch; do { await new Promise(r => setTimeout(r, 2000)); batch = await fetch(`https://www.pixola.ai/api/v1/batches/${batchId}`, { headers: { "Authorization": "Bearer pxk_YOUR_API_KEY" }, }).then(r => r.json()); } while (!["complete", "failed", "rejected"].includes(batch.status)); console.log(batch.images[0].url);