Introduction

The Pixel Engine API gives you programmatic access to Pixel Engine. Submit an image and a prompt, poll until the job finishes, and download the result. POST /animate supports both pixel art animation and general-purpose frame animation. This page covers everything you need to make your first request.

Base URL

https://api.pixelengine.ai/functions/v1

All requests and responses use application/json. All endpoints support CORS.

Authentication

Every request must include a Bearer token in the Authorization header. There are two kinds, and every endpoint accepts both:

Authorization: Bearer pe_sk_...          # API key
Authorization: Bearer eyJhbGciOiJFUzI1...  # OAuth access token

Creating an API key

API keys are managed in your account under Account → API.

1. Sign in and go to Account → API.
2. Click Add key and optionally give it a name.
3. Copy the full key immediately — it is only shown once.

You can hold up to 10 keys per account. Keys can be renamed, deactivated (paused without deletion), or permanently deleted. A deactivated key returns 401 unauthorized on every request until it is reactivated.

OAuth access tokens (Sign in with Pixel Engine)

For desktop apps, tools and services whose users bring their own Pixel Engine account. Users sign in on pixelengine.ai and approve your app on a consent screen that names it; your app never sees their password or an API key. This is standard OAuth 2.1 with PKCE — use any OAuth client library.

Discover the endpoints from the authorization server metadata rather than hardcoding them:

GET https://api.pixelengine.ai/auth/v1/.well-known/oauth-authorization-server

1. Register your app once at the registration_endpoint (dynamic client registration), as a public client: "token_endpoint_auth_method": "none", grant types authorization_code and refresh_token. The client_name you register is what users see on the consent screen. Redirect URIs must match exactly; loopback (http://127.0.0.1:8765/callback) and custom schemes (yourapp://callback) are both accepted.
2. Send the user to the authorization_endpoint in their system browser with response_type=code, your client_id, the redirect_uri, an S256 PKCE challenge, and a state value.
3. Exchange the code returned to your redirect URI at the token_endpoint for an access token and a refresh token.
4. Call any endpoint with Authorization: Bearer <access_token> — requests and responses are identical to API-key use.

Credits

Pixel Engine uses a credit system. Your available balance is the sum of two pools:

Monthly credits are spent first. Purchased credits are only drawn down once your monthly pool is exhausted.

Before a job runs, a hold is placed on the required credits for up to 10 minutes. If the job fails or is cancelled via POST /cancel, the hold is released and no credits are consumed. Credits are only deducted on a successful generation.

Endpoint costs

Check your current balance at any time with GET /balance.

Training opt-out

We may use prompts, uploads and generations to train our models (see the Privacy Policy). There are two ways to opt out:

GET /jobs returns training_opt_out as sent on that request. A value that is not a boolean is rejected with 400 invalid_request.

Errors

All error responses share this shape, regardless of endpoint:

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

code is a stable, machine-readable string — safe to match in application code. message is human-readable and safe to surface to users.

Common error codes

Endpoint-specific errors are documented on the API Reference page.

Polling

POST /animate returns a job ID immediately — generation runs asynchronously in the background. Use GET /jobs to wait for the result.

Recommended pattern

1. Submit with POST /animate. Save the returned api_job_id.
2. Call GET /jobs?id=<api_job_id> every 3–5 seconds while status is "queued" or "pending".
3. Stop polling when status is "success", "failure", or "cancelled". On success, output.url contains a temporary download URL.

Typical generation time is ~90 seconds.

# 1. Submit a job
curl -X POST https://api.pixelengine.ai/functions/v1/animate \
  -H "Authorization: Bearer pe_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded PNG>",
    "prompt": "a character walking left"
  }'

# → { "api_job_id": "f47ac10b-...", "status": "queued", "error": null }

# 2. Poll every 3–5 seconds until a terminal status
curl "https://api.pixelengine.ai/functions/v1/jobs?id=f47ac10b-..." \
  -H "Authorization: Bearer pe_sk_..."

# → on success: output.url holds the download URL

See also

The API Reference contains the full specification for every endpoint: request bodies, all accepted fields and their types, response shapes, status values, metadata formats, and the complete list of error codes per endpoint.