API Reference

Build with GenPicz

Integrate AI image generation directly into your product with our clean REST API. Fast, reliable, and built for scale.

Quick start API requires Studio plan

Overview

The GenPicz API is a RESTful HTTP API that allows you to generate images programmatically from text prompts. All requests are authenticated using API keys and return JSON responses.

Studio plan required. API access is available exclusively to Studio plan subscribers. Upgrade your plan to get started.

Base URL

Base URL
https://api.genpicz.com/v1

All API requests must be made over HTTPS. Requests made over plain HTTP will be rejected. The API uses conventional HTTP response codes to indicate success or failure.

Authentication Studio

GenPicz uses API keys for authentication. You can create and manage your API keys from the Settings → API Keys section of your dashboard.

Keep your API key secret. Never expose it in client-side code, public repositories, or logs. Treat it like a password.

Pass your API key as a Bearer token in the Authorization header of every request:

HTTP
Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Quick Start

Generate your first image in under 60 seconds. Replace YOUR_API_KEY with your key from the dashboard.

cURL

cURL
curl https://api.genpicz.com/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a neon samurai in a cyberpunk city, cinematic lighting",
    "style": "cinematic",
    "width": 1024,
    "height": 1024
  }'

JavaScript (Node / Browser)

JavaScript
const response = await fetch('https://api.genpicz.com/v1/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.GENPICZ_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'a neon samurai in a cyberpunk city',
    style:  'cinematic',
    width:  1024,
    height: 1024,
  }),
});

const { image_url, generation_id } = await response.json();
console.log(image_url); // https://cdn.genpicz.com/gen/abc123.png

Python

Python
import requests

response = requests.post(
    "https://api.genpicz.com/v1/generate",
    headers={
        "Authorization": f"Bearer {GENPICZ_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "prompt": "a neon samurai in a cyberpunk city",
        "style":  "cinematic",
        "width":  1024,
        "height": 1024,
    },
)

data = response.json()
print(data["image_url"])  # https://cdn.genpicz.com/gen/abc123.png

Endpoints

POST /v1/generate

Generate a new image from a text prompt. Returns a URL to the generated image and a generation ID.

GET /v1/generations/{id}

Retrieve the status and result of a specific generation by its ID. Useful for async workflows.

GET /v1/generations

List all past generations for the authenticated account, with pagination support.

DELETE /v1/generations/{id}

Delete a specific generation and remove the associated image from CDN storage.

GET /v1/styles

List all available style presets with IDs, names, and example output thumbnails.

GET /v1/account

Returns account information including remaining credits, plan type, and usage statistics.

Parameters — POST /v1/generate

ParameterTypeDescription
prompt string Required. Text description of the image to generate. Max 1,500 characters.
style string Style preset ID. See /v1/styles for available values. Defaults to "auto".
width integer Output width in pixels. Accepted: 512, 768, 1024, 1280, 1920. Default: 1024.
height integer Output height in pixels. Same accepted values as width. Default: 1024.
quality string Generation quality. One of "standard", "hd", "ultra". Default: "hd".
negative_prompt string Elements to avoid in the output. Max 500 characters.
seed integer Random seed for reproducible results. Omit for a random seed.
upscale boolean Upscale output to 4× resolution. Studio plan only. Default: false.
webhook_url string HTTPS URL to receive a POST callback when generation completes. See Webhooks section.

Response Format

All successful responses return HTTP 200 with a JSON body. Errors return the appropriate HTTP code with an error object.

JSON — Success
{
  "generation_id": "gen_Kz9mN4pQr2xTvW",
  "status":        "completed",
  "image_url":     "https://cdn.genpicz.com/gen/Kz9mN4pQr2xTvW.png",
  "width":         1024,
  "height":        1024,
  "style":         "cinematic",
  "seed":          4829301,
  "created_at":    "2025-06-01T10:32:44Z",
  "credits_used":  1
}
JSON — Error
{
  "error": {
    "code":    "rate_limit_exceeded",
    "message": "You have exceeded 60 requests per minute.",
    "status":  429
  }
}

Rate Limits

Requests are rate-limited per API key, per minute. If you exceed the limit, the API returns HTTP 429. Limits reset at the start of each minute (UTC).

Starter

10

requests / minute

Pro

30

requests / minute

Studio

60

requests / minute

Rate-limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Enterprise customers with higher volume requirements can contact us to discuss dedicated rate limit tiers.

Error Codes

400
bad_requestThe request body is malformed or a required parameter is missing.
401
unauthorizedMissing or invalid API key. Check your Authorization header.
402
payment_requiredYour account has insufficient credits or an expired subscription.
403
forbiddenAPI access requires a Studio plan subscription.
404
not_foundThe requested resource (generation ID, style) does not exist.
422
content_policy_violationThe prompt was rejected by the content safety filter.
429
rate_limit_exceededToo many requests. Wait until the next rate-limit window resets.
500
internal_errorAn unexpected error occurred on our servers. Retry with exponential backoff.

Webhooks

For asynchronous workflows, pass a webhook_url in your generate request. When generation completes, GenPicz will POST the result payload to that URL.

Webhook URLs must be HTTPS and publicly accessible. Requests will retry up to 3 times with exponential backoff on non-2xx responses.
Webhook Payload
{
  "event":         "generation.completed",
  "generation_id": "gen_Kz9mN4pQr2xTvW",
  "status":        "completed",
  "image_url":     "https://cdn.genpicz.com/gen/Kz9mN4pQr2xTvW.png",
  "created_at":    "2025-06-01T10:32:44Z"
}

Validate webhook authenticity by checking the X-GenPicz-Signature header, which is an HMAC-SHA256 of the raw request body using your webhook secret.

SDKs & Libraries

Official SDK packages are currently in development and will be published shortly. In the meantime, the API is straightforward to use with any standard HTTP library.

NPM @genpicz/sdk — coming soon

JavaScript / TypeScript SDK for Node.js and browser environments.

PyPI genpicz — coming soon

Python SDK with async support via asyncio.

Questions about the API? Contact our developer support team.