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 2 to 10 animation jobs in a single request. Sub-jobs run sequentially on a single warm GPU container, sharing the cold-start cost. Returns immediately with one batch ID and an array of per-sub-job IDs. Poll the entire batch with GET /batch-jobs, or any individual sub-job with GET /jobs.

Cost: 20 credits for the first sub-job (the anchor), then 12 credits for each additional sub-job. The anchor charge is not refunded if the anchor sub-job fails — see Pricing below.

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,
      "seed": 12345
    },
    {
      "image": "<base64>",
      "prompt": "the same character running",
      "model": "pixel-engine-v1.1",
      "output_frames": 8
    }
  ]
}

Constraints

• Batch size: Between 2 and 10 sub-jobs.
• Same pipeline: Every sub-job's model must resolve to the same pipeline (all pixel-engine OR all frame-engine).
• Per-image limit: 5 MB decoded per image (same as POST /animate).
• Aggregate image limit: 30 MB total across all jobs[i].image values combined.

Pricing

The first sub-job in the batch is the anchor. The 20-credit anchor hold is captured on either "success" or "failure" — it covers the cold-start GPU time and is not refunded if the anchor sub-job fails. It is refunded only when a POST /cancel arrives before the anchor begins processing.

Sub-jobs at positions 1 and beyond cost 12 credits each and follow the standard rules: charged on "success", refunded on "failure" or "cancelled".

Formula: 20 + 12 × (N − 1) = 12N + 8 credits when every sub-job succeeds.

Response

{
  "batch_id": "9b1c8f24-3e1c-4d2a-b6e8-1f1e2d3c4b5a",
  "api_job_ids": [
    "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "a3d7c0d2-fbf1-43b6-baf8-deadbeef0001"
  ],
  "status": "queued"
}

api_job_ids[i] matches the input jobs[i]. Use GET /batch-jobs?batch_id=<batch_id> to poll every sub-job in one request, or GET /jobs?id=<api_job_id> for any individual sub-job.

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 cancelled sub-jobs are released immediately.

Cost: Free — does not deduct credits.

Request body

Provide exactly one of api_job_id or batch_id.

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

{
  "batch_id": "9b1c8f24-3e1c-4d2a-b6e8-1f1e2d3c4b5a"
}

Response — single-job

Returned when the cancelled job is not part of a batch.

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

Response — batch (request used batch_id)

Returned when the request body specified batch_id directly.

{
  "batch_id": "9b1c8f24-3e1c-4d2a-b6e8-1f1e2d3c4b5a",
  "status": "cancelled",
  "cancelled_count": 7
}

Response — batch (request used a sub-job api_job_id)

Returned when the request body specified api_job_id and that job belongs to a batch. Includes both the originally requested api_job_id (echoed for confirmation) and the resolved batch_id so the caller can correlate.

{
  "api_job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "batch_id": "9b1c8f24-3e1c-4d2a-b6e8-1f1e2d3c4b5a",
  "status": "cancelled",
  "cancelled_count": 7
}

Response fields

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.

Batch sub-jobs

When the polled job is part of a batch (created by POST /animate-batch), the response also includes:

These fields are absent for jobs submitted via POST /animate or any other single-job endpoint. To poll an entire batch in one request, use GET /batch-jobs instead.

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 in one request, ordered by batch_position. Use this instead of polling each sub-job individually with GET /jobs. Output URLs and error envelopes are included as soon as each sub-job finalizes.

Query parameters

Response

{
  "batch_id": "9b1c8f24-3e1c-4d2a-b6e8-1f1e2d3c4b5a",
  "batch_size": 3,
  "summary": {
    "queued": 0,
    "pending": 1,
    "success": 1,
    "failure": 1,
    "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": "...", "model": "pixel-engine-v1.1", "output_frames": 8 },
      "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": "a3d7c0d2-fbf1-43b6-baf8-deadbeef0001",
      "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": "...", "model": "pixel-engine-v1.1", "output_frames": 8 },
      "output": null,
      "error": null
    },
    {
      "api_job_id": "b4e8d1e3-abcd-4321-9876-deadbeef0002",
      "batch_position": 2,
      "status": "failure",
      "progress": 0.0,
      "created_at": "2026-03-02T18:00:00.000Z",
      "finished_at": "2026-03-02T18:02:10.000Z",
      "cancelled_at": null,
      "billing": {
        "credits_held": 12,
        "credits_charged": 0,
        "hold_status": "released"
      },
      "inputs": { "prompt": "...", "model": "pixel-engine-v1.1", "output_frames": 8 },
      "output": null,
      "error": {
        "code": "generation_failed",
        "message": "Generation failed"
      }
    }
  ]
}

Top-level fields

Sub-job fields

Each entry in sub_jobs mirrors a GET /jobs response — see GET /jobs for the full schema (status values, billing object, output object, error envelopes, metadata shapes). Differences:

• batch_position is always present (it is only conditional on GET /jobs).
• The wrapper batch_id field on each sub-job is omitted to avoid repeating it on every entry — it appears once at the top level instead.
• Sub-jobs whose output has been cleaned up (24-hour retention) return output: null and an error envelope with code job_expired, rather than failing the entire batch response.

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.