API Reference

All endpoints are relative to https://api.pixelengine.ai/functions/v1. Every request requires an API key.

GET/balance

Returns the authenticated user's current credit balance.

Response

Response 200

{
  "monthly_balance": 1200,
  "purchased_balance": 500,
  "total_balance": 1700,
  "reserved": 20,
  "available": 1680
}

Field	Type	Description
`monthly_balance`	integer	Current monthly credit pool.
`purchased_balance`	integer	Current purchased credit pool.
`total_balance`	integer	`monthly_balance + purchased_balance`.
`reserved`	integer	Credits held by in-flight jobs (not yet deducted).
`available`	integer	Credits available for new jobs (`total_balance − reserved`, floor 0).

Errors

HTTP	Code	Cause
401	`unauthorized`	Invalid or inactive API key.

POST/animate

Submits an image-to-video pixel art generation job. Returns immediately with a job ID; generation runs asynchronously. Poll GET /jobs to track progress.

Cost: 20 credits (subject to per-user discount).

Request body

JSON

{
  "image": "<base64-encoded PNG or data URL>",
  "prompt": "a character walking through a forest",
  "negative_prompt": "blurry, distorted",
  "pixel_config": { "colors": 16 },
  "output_frames": 8,
  "output_format": "webp",
  "matte_color": "#808080"
}

Field	Type	Required	Description
`image`	string	Yes	Base64-encoded PNG, or a data URL (`data:image/png;base64,…`). See image constraints below.
`prompt`	string	Yes	Non-empty text describing the desired animation.
`negative_prompt`	string	No	What to avoid in the generation.
`pixel_config`	object	No	Color palette config. Defaults to `{ "colors": 24 }`. See PixelConfig below.
`output_frames`	integer	No	Number of animation frames. Even integer between 2–16. Default: 8. Played back at 8 fps.
`output_format`	string	No	`"webp"` (default), `"gif"`, or `"spritesheet"`.
`matte_color`	string	No	6-character hex color (e.g. `"#ff0000"`) used to flatten the alpha channel of the input PNG before processing. Default: `"#808080"` (50% gray).

PixelConfig

Provide one of two modes — never both. If pixel_config is omitted entirely, defaults to count mode with 24 colors.

Count mode — cluster output to N colors

{ "colors": 24 }

Palette mode — force specific colors

{ "palette": ["#ffaa00", "#223344", "#ffffff"] }

Field	Type	Constraints
`colors`	integer	2–256.
`palette`	string[]	Array of hex color strings (e.g. `"#ff0000"`)

Palette mode is an experimental feature. Forcing a specific palette can produce worse results than letting the model choose its own colors. If quality matters more than exact color matching, prefer count mode (colors).

Image constraints

Format: PNG only. Validated via magic bytes; data URL prefix is stripped automatically.
Max decoded size: 5 MB.
Max dimension: 256 px per axis (width or height).
Max aspect ratio: 2:1 in either orientation (e.g. 256×128 is ok; 256×100 is not).
Alpha: flattened onto a matte color before processing. Defaults to mid-grey (#808080); override with matte_color.

Response

Response 200

{
  "api_job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "queued",
  "error": null
}

Errors

HTTP	Code	Cause
400	`invalid_request`	Missing or invalid field (prompt, image format, output_frames, etc.).
400	`image_too_large`	Image exceeds 5 MB decoded.
401	`unauthorized`	Invalid or inactive API key.
402	`insufficient_credits`	Not enough available credits.
500	`internal_error`	Server-side failure.

GET/jobs

Returns the current state of a job. On completion, includes a signed download URL or error details.

Query parameters

Parameter	Required	Description
`id`	Yes	The `api_job_id` returned by `POST /animate`.

Response

Response 200 — queued

{
  "api_job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "queued",
  "progress": 0.0,
  "created_at": "2026-03-02T18:00:00.000Z",
  "finished_at": null,
  "output": null,
  "error": null
}

Status values

Value	Meaning
`"queued"`	Job accepted, waiting to be picked up.
`"pending"`	Job is actively running.
`"success"`	Generation complete. `output` is populated.
`"failure"`	Generation failed. `error` is populated.

progress is a float 0.0–1.0. May remain 0 until the job is actively running.

Output object (on success)

output — status: "success"

{
  "url": "https://...",
  "content_type": "image/webp",
  "metadata": { ... },
  "expires_at": "2026-03-03T18:00:00.000Z"
}

Field	Description
`url`	Pre-signed download URL. Valid for 1 hour. Re-poll to get a fresh URL after expiry.
`content_type`	`"image/webp"`, `"image/gif"`, or `"image/png"` (spritesheet).
`metadata`	Output dimensions and format details. See shapes below.
`expires_at`	ISO timestamp when the output file is permanently deleted (24 hours after job creation).

Output files are permanently deleted 24 hours after job creation — after that, polling returns 410 job_expired. The signed url is valid for 1 hour; re-poll GET /jobs to get a fresh one before it expires.

Metadata shapes

webp and gif

{ "width": 64, "height": 64, "frame_count": 8, "fps": 8.0 }

spritesheet

{
  "width": 512,
  "height": 64,
  "output_format": "spritesheet",
  "frame_count": 8,
  "frame_w": 64,
  "frame_h": 64
}

Spritesheets are a single horizontal strip: width == frame_count × frame_w, height == frame_h. Output dimensions always match the original input image, regardless of internal upscaling.

Error object (on failure)

error — status: "failure"

{
  "code": "generation_failed",
  "message": "Generation failed"
}

Errors

HTTP	Code	Cause
400	`invalid_request`	`id` query parameter missing.
401	`unauthorized`	Invalid or inactive API key.
404	`job_not_found`	No job with that ID, or the job belongs to a different API key.
410	`job_expired`	Job output has been deleted. Outputs are retained for 24 hours.
500	`internal_error`	Server-side failure.

API Reference

Response

Errors

Request body

PixelConfig

Image constraints

Response

Errors

Query parameters

Response

Status values

Output object (on success)

Metadata shapes

Error object (on failure)

Errors

See also