Skip to content

Quickstart

From a new account to a rendered file. Everything here works on the free plan with a test key, so it costs nothing.

1. Get a test key#

Create a workspace at pixbix.app/sign-up, then go to Settings → API keys and create a key with the test environment selected.

Test keys are free

A pk_test_ key runs the real rendering pipeline, consumes no credits, and always watermarks the output. Build the whole integration on one before you spend anything.

The key is shown once. Store it in an environment variable, not in your source.

Shell
export PIXBIX_KEY="pk_test_1a2b3c4d…"

2. Pick a template#

Start from the public library — a set of finished designs anyone can copy — so you have something to render before designing your own.

cURL
curl "https://pixbix.app/api/v1/templates?scope=library&kind=image" \
  -H "x-api-key: $PIXBIX_KEY"

Now copy the one you want into your workspace. This step is required, and it is the only route from the library to a render: you render your copy, never somebody else’s original. Every row in the list above carries canRender, which is false for anything you do not yet own.

curl -X POST https://pixbix.app/api/v1/templates/quote-card/duplicate \
  -H "x-api-key: $PIXBIX_KEY"
The copy arrives as a draft, and a draft cannot be rendered. Publish it with PATCH /templates/:id sending { "status": "published" }, or from the dashboard. Everything from here uses your copy’s id.

Then read its field schema — that tells you exactly what to send, and confirms with canRender that a render will be accepted.

curl https://pixbix.app/api/v1/templates/tpl_9c41b2 \
  -H "x-api-key: $PIXBIX_KEY"

3. Render an image#

Still images render synchronously — the response contains the finished URL. No polling, no webhook.

curl -X POST https://pixbix.app/api/v1/render \
  -H "x-api-key: $PIXBIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "tpl_9c41b2",
    "values": {
      "quote": "Design once. Generate forever.",
      "author": "pixbix",
      "accent": "#00C4CC"
    }
  }'

Prefer the bytes over a URL? Add ?format=binary and the response body is the image itself — useful when you are piping straight into another system.

4. Render a video#

Video is queued rather than returned inline. You get a render id immediately, then either poll it or — better — receive a webhook when it lands.

curl -X POST https://pixbix.app/api/v1/render \
  -H "x-api-key: $PIXBIX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "story-reel",
    "values": { "headline": "Launch day", "subtext": "Now live" },
    "output": { "format": "mp4", "resolution": "fhd", "fps": 30 }
  }'

# → 202 { "data": { "id": "rnd_8f2a1c", "status": "queued" } }

Use webhooks in production

Polling works, but it costs you a request every two seconds per render. Register a webhook and the result is pushed to you the moment it is ready — in whatever shape your receiver expects, since the method, encoding, headers and payload are all configurable. See the webhooks guide.

5. Go live#

When the integration works end to end, switch to a live key. Before you do:

  1. Create a pk_live_ key and store it separately from the test key.
  2. Add an Idempotency-Key to every render request, so a retry cannot bill twice.
  3. Handle 402 INSUFFICIENT_CREDITS — surface it, do not retry it.
  4. Register a webhook endpoint and verify signatures.
  5. Check POST /v1/render/estimate if you need to show cost before committing.

Watermarks

Test keys always watermark. If your live renders are still watermarked, your workspace is on the free plan — any paid plan removes it.