API Reference

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

Returns the authenticated user's current credit balance.

Response

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

Errors

Returns a billing summary for the authenticated user over a given date range, plus a current balance snapshot. Useful for tracking credit spend and understanding usage over time.

Query parameters

The maximum period is 365 days.

Response

{
  "period": {
    "start_date": "2026-03-01T00:00:00.000Z",
    "end_date": "2026-03-31T23:59:59.999Z"
  },
  "totals": {
    "credits_used": 1240,
    "credits_added": 1200,
    "refunds": 40,
    "net_change": 0,
    "jobs_charged": 62
  },
  "balance": {
    "monthly_balance": 920,
    "purchased_balance": 500,
    "total_balance": 1420,
    "reserved": 20,
    "available": 1400
  }
}

Errors

Submits an image-to-video generation job. The endpoint supports both pixel art animation and general-purpose frame animation. Returns immediately with a job ID; generation runs asynchronously. Poll GET /jobs to track progress.

Cost: 20 credits.

Request body

{
  "image": "<base64-encoded image or data URL>",
  "prompt": "a character walking through a forest",
  "model": "pixel-engine-v1.1",
  "negative_prompt": "blurry, distorted",
  "pixel_config": { "colors": 16 },
  "output_frames": 8,
  "seed": 12345,
  "output_format": "webp",
  "matte_color": "#808080"
}

Models

If model is omitted, the API defaults to "pixel-engine-v1.1".

PixelConfig

pixel_config is only valid for "pixel-engine-v1.1" (or when model is omitted, since that defaults to the pixel model). Provide one of two modes — never both. If pixel_config is omitted entirely, it defaults to count mode with 24 colors.

{ "colors": 24 }

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

Image constraints

Data URL prefixes are stripped automatically.

• Max decoded size: 5 MB for both models.
• Aspect ratio: Between 1:2 and 2:1 for both models.
• Alpha: flattened onto matte_color before processing.

output_frames must be an even integer starting at 2. The maximum is 16 for "pixel-engine-v1.1" and 24 for "frame-engine-v1.1".

Response

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

Errors

Common validation failures include unsupported image formats for the chosen model, pixel_config being sent with "frame-engine-v1.1", images smaller than 256×256 px for "frame-engine-v1.1", and odd or out-of-range output_frames values.

Submits a keyframe-conditioned generation job. Provide one or more reference images at specific frame positions, and the model interpolates between them to produce a full animation. Supports both pixel art and general-purpose output. Returns immediately with a job ID; generation runs asynchronously. Poll GET /jobs to track progress.

Cost: 24 credits.

Request body

{
  "prompt": "a character walking cycle",
  "render_mode": "pixel",
  "total_frames": 8,
  "frames": [
    { "index": 0, "image": "<base64>", "strength": 1.0 },
    { "index": 4, "image": "<base64>", "strength": 0.8 },
    { "index": 7, "image": "<base64>", "strength": 1.0 }
  ],
  "negative_prompt": "blurry, distorted",
  "pixel_config": { "colors": 24 },
  "seed": 12345,
  "output_format": "webp",
  "matte_color": "#808080"
}

Render modes

Image constraints

Data URL prefixes are stripped automatically.

• Max per image: 10 MB decoded.
• Max total: 20 MB across all keyframes combined.
• Aspect ratio: Between 1:2 and 2:1.
• Consistency: All keyframe images must have the same dimensions.
• Alpha: flattened onto matte_color before processing.

Response

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

Errors

Regenerates a range of frames within an existing animation. Provide the source animation (WebP or GIF) and a frame range to retake — the model keeps all other frames frozen and regenerates only the selected region. Returns immediately with a job ID; generation runs asynchronously. Poll GET /jobs to track progress.

Cost: 24 credits.

Request body

{
  "prompt": "a character walking cycle",
  "render_mode": "pixel",
  "image": "<base64-encoded webp or gif>",
  "retake_region": { "start_frame": 2, "end_frame": 5 },
  "negative_prompt": "blurry, distorted",
  "pixel_config": { "colors": 24 },
  "seed": 12345,
  "output_format": "webp",
  "matte_color": "#808080"
}

Retake region

{ "start_frame": 2, "end_frame": 5 }

Frame bounds are validated against the actual frame count of the source animation on the server. If end_frame exceeds the last frame index, the job will fail with an error.

Source animation constraints

• Format: WebP or GIF.
• Max size: 20 MB.
• Data URLs: Prefixes are stripped automatically.

Response

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

Errors

Converts an image to clean pixel art. Automatically detects the pixel grid, quantizes colors, and resamples the image to the detected grid resolution. Returns immediately with a job ID; processing runs asynchronously. Poll GET /jobs to track progress and retrieve the output PNG.

Cost: Free — does not deduct credits.

Request body

{
  "image": "<base64-encoded image or data URL>",
  "colors": 24
}

Image constraints

Data URL prefixes are stripped automatically.

• Format: PNG or JPEG.
• Max decoded size: 10 MB.
• Max dimension: 2048 px on either axis.
• Aspect ratio: Between 1:2 and 2:1.

Response

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

Poll GET /jobs?id=<api_job_id> for status. On success, output.content_type will be "image/png" and output.metadata will contain width and height of the output image.

Errors

Cancel a queued or in-progress job. Credits held for the job are released immediately.

Cost: Free — does not deduct credits.

Request body

{
  "api_job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Response

{
  "api_job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "cancelled"
}

Errors

Rewrites a short user prompt into a precise animation caption optimized for the generation model. Optionally accepts a reference image — when provided, the AI identifies the character from the image rather than inventing appearance details. This is a synchronous endpoint; the result is returned directly (typically 1–3 seconds).

Cost: Free — does not deduct credits.

Request body

{
  "prompt": "dash sword attack",
  "image": "<base64-encoded image or data URL>",
  "model": "pixel-engine-v1.1"
}

Models

The model field should match the model you intend to use with POST /animate. Image constraints are enforced per model. If omitted, defaults to "pixel-engine-v1.1".

Image constraints

Same per-model constraints as POST /animate. Data URL prefixes are stripped automatically.

• Max decoded size: 5 MB for both models.
• Aspect ratio: Between 1:2 and 2:1 for both models.

Response

{
  "enhanced_prompt": "The character dashes forward with a burst of speed, executing a wide, sweeping sword slash that leaves a large white crescent trail."
}

Behavior

When an image is provided, the model uses it as a reference for the rewritten caption. Without an image, it rewrites based on the text prompt alone. If only an image is provided, it generates a generic caption from the image.

Errors

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

Query parameters

Response

{
  "api_job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "queued",
  "progress": 0.0,
  "created_at": "2026-03-02T18:00:00.000Z",
  "finished_at": null,
  "cancelled_at": null,
  "billing": {
    "credits_held": 20,
    "credits_charged": 0,
    "hold_status": "open"
  },
  "inputs": {
    "prompt": "a character walking through a forest",
    "negative_prompt": "",
    "model": "pixel-engine-v1.1",
    "pixel_config": { "colors": 16 },
    "output_frames": 8,
    "seed": 12345,
    "output_format": "webp",
    "matte_color": "#808080"
  },
  "output": null,
  "error": null
}

Status values

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

cancelled_at is an ISO-8601 timestamp set when a job is cancelled via POST /cancel, otherwise null.

Billing object

Present whenever a wallet hold was created for the job. null if no hold exists.

{
  "credits_held": 20,
  "credits_charged": 0,
  "hold_status": "open"
}

Inputs object

Reflects the generation parameters submitted with POST /animate, POST /keyframes, POST /retake, or POST /pixelate. Always present. Fields match the original request body (excluding image / image_url). If seed was not provided in the original request, it will be absent here.

Output object (on success)

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

Metadata shapes

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

{
  "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)

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

Error object (on cancel)

{
  "code": "job_cancelled",
  "message": "Job was cancelled"
}

Errors

See also

The Introduction covers everything needed before making your first request: base URL, authentication and API key management, the credit system, the shared error response format, and the recommended polling pattern for async jobs.