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 multiple image-to-video jobs in a single request (2–10 sub-jobs). The whole batch runs sequentially inside one warm GPU container, which amortizes the cold-start cost across every sub-job — so a batch is cheaper per animation than submitting the same jobs one at a time through POST /animate. Returns immediately with a batch ID and one job ID per sub-job; generation runs asynchronously. Poll GET /batch-jobs to track the whole batch at once.

Cost: The first sub-job (the anchor) costs 20 credits; each additional sub-job costs 12 credits. A batch of N sub-jobs costs 20 + 12 × (N − 1) credits — e.g. 5 jobs = 68 credits vs. 100 if submitted individually.

Request body

{
  "jobs": [
    {
      "image": "<base64-encoded image or data URL>",
      "prompt": "a character walking through a forest",
      "model": "pixel-engine-v1.1",
      "pixel_config": { "colors": 16 },
      "output_frames": 8
    },
    {
      "image": "<base64-encoded image or data URL>",
      "prompt": "a character drawing its sword",
      "model": "pixel-engine-v1.1"
    }
  ]
}

Image constraints

Each sub-job image follows the same per-model rules as POST /animate (format, dimensions, aspect ratio, alpha handling). In addition:

• Max per image: 5 MB decoded.
• Max total: 30 MB decoded across all sub-jobs combined.

Billing

A separate hold is placed for each sub-job at submission. The anchor (the first sub-job) pays a non-refundable cold-start fee: it is charged on both success and failure, and is only released if the batch is cancelled before the anchor runs. Every other sub-job follows the normal hold rules — released on failure or cancellation, charged only on success.

Response

{
  "batch_id": "b1f2c3d4-5678-90ab-cdef-1234567890ab",
  "api_job_ids": [
    "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "9c858901-8a57-4791-81fe-4c455b099bc9"
  ],
  "status": "queued"
}

Errors

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

Generates a still pixel-art image from a text prompt. Optionally accepts a reference image (base64 or URL) — when provided, the model edits/transforms the reference instead of generating from scratch (image-to-image). Returns immediately with a job ID; generation runs asynchronously. Poll GET /jobs to track progress and retrieve the output PNG.

Cost: Varies by model (6–36 credits). See Models below.

Request body

{
  "prompt": "a knight standing in a torchlit dungeon",
  "model": "nb_flash",
  "pixel_config": { "colors": 24 },
  "seed": 12345
}

{
  "prompt": "the same character, now wearing a red cape",
  "model": "oai_gpt2_medium",
  "image": "<base64-encoded image or data URL>",
  "pixel_config": { "palette": ["#1a1a1a", "#c83232", "#f0c878", "#ffffff"] }
}

Models

If model is omitted, the API defaults to "nb_flash". Cost is a flat per-model charge (no surcharge for the optional reference image).

PixelConfig

Required on this endpoint — every output is post-processed into pixel art. Provide one of two modes, never both.

{ "colors": 24 }

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

Image constraints (reference image)

Only applies when image or image_url is provided. Data URL prefixes are stripped automatically.

• Format: PNG or JPEG.
• Max decoded size: 5 MB.
• image_url: Must be an HTTPS URL.

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 generated image.

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

Removes the background from a still PNG or animated WebP, returning the same format with a transparent background. No prompt or model selection — this is a pure image-processing operation. Returns immediately with a job ID; processing runs asynchronously. Poll GET /jobs to track progress and retrieve the output.

Cost: 2 credits.

Run this endpoint after POST /animate or POST /keyframes completes to strip the background from the generated animation.

Request body

{
  "image": "<base64-encoded image or data URL>",
  "rmbg_alpha_threshold": 128
}

Image constraints

Data URL prefixes are stripped automatically.

• Format: PNG or WebP (still or animated WebP both supported).
• Max decoded size: 10 MB.
• Dimensions: No fixed cap. Larger inputs take longer to process.

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 matches the input format — "image/png" for PNG inputs, "image/webp" for WebP inputs (animated WebP stays animated). output.metadata.rmbg_threshold reflects the threshold value that was applied.

Errors

Cancel a queued or in-progress job, or an entire batch. Credits held for the cancelled job(s) are released immediately. Provide exactly one of api_job_id or batch_id.

Cost: Free — does not deduct credits.

Request body

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

{
  "batch_id": "b1f2c3d4-5678-90ab-cdef-1234567890ab"
}

Response

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

{
  "batch_id": "b1f2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "cancelled",
  "cancelled_count": 3
}

For a batch, cancelled_count is the number of sub-jobs that were non-terminal at cancel time and have now been 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 /generate-image, POST /pixelate, or POST /remove-background. 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

Output dimensions depend on whether the job runs in a pixel-art pipeline or a general-purpose pipeline, not on the output format. All formats (webp, gif, spritesheet) for a given job render at the same per-frame resolution.

Error object (on failure)

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

Error object (on cancel)

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

Errors

Returns the current state of every sub-job in a batch, plus a roll-up summary. Poll this once per interval to track an entire POST /animate-batch submission instead of polling each sub-job individually.

Cost: Free — does not deduct credits.

Query parameters

Response

{
  "batch_id": "b1f2c3d4-5678-90ab-cdef-1234567890ab",
  "batch_size": 2,
  "summary": {
    "queued": 0,
    "pending": 1,
    "success": 1,
    "failure": 0,
    "cancelled": 0
  },
  "sub_jobs": [
    {
      "api_job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "batch_position": 0,
      "status": "success",
      "progress": 1.0,
      "created_at": "2026-03-02T18:00:00.000Z",
      "finished_at": "2026-03-02T18:01:30.000Z",
      "cancelled_at": null,
      "billing": { "credits_held": 20, "credits_charged": 20, "hold_status": "captured" },
      "inputs": { "prompt": "a character walking", "model": "pixel-engine-v1.1" },
      "output": {
        "url": "https://...",
        "content_type": "image/webp",
        "metadata": { "width": 64, "height": 64, "frame_count": 8, "fps": 8.0 },
        "expires_at": "2026-03-03T18:00:00.000Z"
      },
      "error": null
    },
    {
      "api_job_id": "9c858901-8a57-4791-81fe-4c455b099bc9",
      "batch_position": 1,
      "status": "pending",
      "progress": 0.4,
      "created_at": "2026-03-02T18:00:00.000Z",
      "finished_at": null,
      "cancelled_at": null,
      "billing": { "credits_held": 12, "credits_charged": 0, "hold_status": "open" },
      "inputs": { "prompt": "a character jumping", "model": "pixel-engine-v1.1" },
      "output": null,
      "error": null
    }
  ]
}

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.