API Reference

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

Idempotent retries

A submit request can time out before its response arrives, leaving you unsure whether the job was created. To make retries safe, send an Idempotency-Key header with any request that creates jobs: /animate, /animate-batch, /generate-image, /keyframes, /pixelate and /remove-background. Choose a new key for each logical request (a UUID, or an ID from your own system) and send the same key with every retry of it.

POST /animate
Authorization: Bearer pe_sk_...
Idempotency-Key: 8f14e45f-ceea-4672-a7a3-6f0e1b2c3d4e
Content-Type: application/json

{ "image": "...", "prompt": "walk cycle, facing right" }

The first request with a key creates the job as usual. A later request with the same key creates nothing and charges nothing: it returns the original job with "replayed": true and that job's current status, even if the first request is still being processed. error is null unless that job has failed.

{
  "api_job_id": "3f6c2b1e-...",
  "status": "pending",
  "error": null,
  "replayed": true
}

In the rare case that a retry arrives just as the original fails, the retry gets a 409 idempotency_key_in_use; send it again and it will run.

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. For the individual charges behind these totals, use GET /billing/entries.

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,
    "adjustments": 0,
    "net_change": -80,
    "jobs_charged": 62
  },
  "balance": {
    "monthly_balance": 920,
    "purchased_balance": 500,
    "total_balance": 1420,
    "reserved": 20,
    "available": 1400
  }
}

Errors

Returns the authenticated user's credit history line by line, newest first: every charge, credit purchase, monthly refresh, refund and adjustment. Each charge carries the api_job_id it paid for, so you can match spend to your own records. Results are paged with a cursor; there is no limit on how far back you can go.

Query parameters

Response

{
  "entries": [
    {
      "id": 220470,
      "created_at": "2026-10-19T20:37:15.60985+00:00",
      "type": "debit",
      "amount": 20,
      "change": -20,
      "description": "api animation generation",
      "api_job_id": "b005abb6-32a9-428e-b124-775c8dcd5d82",
      "job_id": null,
      "balance_after": { "monthly": 2085, "purchased": 10978, "total": 13063 }
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0xOVQyMDozNzoxNS42MDk4NSswMDowMCIsImkiOjIyMDQ3MH0"
}

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 on pixel-engine-v1.1 and frame-engine-v1.1; 26 credits on pixel-engine-v1.5, which is slower to start.

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",
  "transform": {
    "canvas_size": 128,
    "fill_method": "edge-extend",
    "offset_x": 0,
    "offset_y": 0
  }
}

Models

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

PixelConfig

pixel_config is only valid in pixel mode — that is "pixel-engine-v1.1", model omitted (which defaults to it), or "pixel-engine-v1.5" with render_mode: "pixel". 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 rules differ by model. On "pixel-engine-v1.5" it is any integer from 3 to 16 — odd counts included. On the -engine- models it must be an even integer starting at 2, with a maximum of 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 outside pixel mode, images smaller than 256×256 px in detailed mode, and out-of-range output_frames values — or odd ones on the -engine- models, which take even counts only.

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,
      "placement": { "offset_x": 4, "offset_y": -2, "flip_h": true } },
    { "index": 7, "image": "<base64>", "strength": 1.0 }
  ],
  "transform": { "canvas_size": 128, "fill_method": "edge-extend" },
  "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 — unless you supply a transform, which places them all on one shared canvas and lets their input sizes differ.
• Alpha: flattened onto matte_color before processing.

Response

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

Errors

Transform

An optional transform places your image on a larger square canvas before generation — useful when your subject is cropped tight and you want room around it for the animation to move into, or when you want a consistent output size regardless of what you sent. Accepted by POST /animate and POST /keyframes. Omit it and the image is used as-is.

{
  "transform": {
    "canvas_size": 128,
    "fill_method": "edge-extend",
    "fill_color": "#808080",
    "offset_x": 0,
    "offset_y": 0,
    "flip_h": false,
    "flip_v": false
  }
}

On /keyframes, the object splits in two

Every keyframe has to land on the same canvas — the interpolation model requires it. So transform carries only the shared parts (canvas_size, fill_method, fill_color), and each keyframe positions itself with its own placement:

{
  "transform": { "canvas_size": 128, "fill_method": "solid", "fill_color": "#1a1a2e" },
  "frames": [
    { "index": 0, "image": "<base64>",
      "placement": { "offset_x": 4, "offset_y": -2, "flip_h": true } },
    { "index": 7, "image": "<base64>",
      "placement": { "offset_x": 0, "offset_y": 6 } }
  ]
}

A placement accepts only offset_x, offset_y, flip_h and flip_v — there is no per-frame size or fill, so one keyframe can never end up on a different canvas than the rest. Any placement you omit defaults to centered and unflipped.

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_2_1",
  "pixel_config": { "colors": 24 },
  "seed": 12345
}

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

{
  "prompt": "the knight from the first reference holding the sword from the second",
  "model": "nb_flash_2_1",
  "reference_images": [
    { "image_url": "https://example.com/knight.png" },
    { "image": "<base64-encoded image or data URL>" }
  ],
  "pixel_config": { "colors": 24 }
}

Models

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

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.5",
  "render_mode": "pixel"
}

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, every model.
• Aspect ratio: Between 1:2 and 2:1, every model.

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"
  },
  "training_opt_out": false,
  "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.

training_opt_out is true when the request that created the job sent "training_opt_out": true. An account-wide opt-out is not reflected here. See Training opt-out.

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

Call /jobs with no id to list your most recent jobs, newest first. To retry a submit whose response never arrived without paying twice, prefer an Idempotency-Key: a job still in validation may not appear in this list yet. An API key sees the jobs it submitted; an OAuth access token sees the jobs that app submitted for that user.

GET /jobs?since=2026-09-30T12:00:00Z&limit=20

Query parameters

Response

{
  "jobs": [
    {
      "api_job_id": "18f9f71c-23fa-4a5a-9290-ba9f267f37a4",
      "status": "success",
      "progress": 1,
      "job_mode": "animate",
      "created_at": "2026-10-01T01:07:50.405Z",
      "finished_at": "2026-10-01T01:09:49.953Z",
      "cancelled_at": null,
      "output_expired": false,
      "billing": { "credits_held": 26, "credits_charged": 26, "hold_status": "captured" },
      "inputs": { "prompt": "…", "model": "pixel-engine-v1.5", "output_frames": 4 },
      "error": null
    }
  ],
  "has_more": true,
  "next_before": "2026-10-01T01:07:50.405Z"
}

Each entry has the same fields as a single GET /jobs?id= response except output: fetch the job by id for its download URL. output_expired is true once the output is no longer available (possible from 24 hours after the job). Batch sub-jobs also carry batch_id and batch_position.

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.