Skip to content
jsontoimg
Start free

SDKs and reference

CLI

The j2i CLI lets you create renders, wait for jobs, download assets, mint signed URLs, and inspect template schemas from your terminal or CI pipelines.

For TypeScript apps, use the Node.js SDK. For raw HTTP endpoints, see the API reference.

Install

npm install -g @j2i/cli
pnpm add -g @j2i/cli
yarn global add @j2i/cli
bun add --global @j2i/cli

Or run without installing:

npx @j2i/cli --help
pnpm dlx @j2i/cli --help
yarn dlx @j2i/cli --help
bun x @j2i/cli --help

The binary name is j2i. From this repo: bun run j2i -- --help.

Auth and global options

Create an API key in the dashboard, then set it in your environment. See Authentication.

export JSONTOIMG_API_KEY=sk_...
Flag Environment variables Meaning
--api-key <key> JSONTOIMG_API_KEY, RENDER_API_KEY API key (required)
--base <url> JSONTOIMG_API_URL, RENDER_BASE_URL API origin (default https://app.jsontoimg.com)
--json — Machine-readable errors (JSON on stderr)
-h, --help — Show help 
j2i schema <template-id>

Commands

Command Purpose
render Create a render (optionally wait and download)
wait <id> Wait for a render to finish
status <id> Get current render job status
download <id> Download the render asset
batch Create a batch from a JSON file
batch-status <id> Get batch status
sign Mint a signed CMS / OG image URL
sign-batch Mint up to 50 signed URLs
schema <templateId> Get template layer schema
templates List templates

render

Creates a render. By default waits up to 60 seconds. Use --async to return as soon as the job is queued.

Flag Required? Notes
--payload <file> one of payload/template Full create-render JSON
--template <id> one of payload/template Minimal body with only the template ID
--format <fmt> no png | jpg | webp | pdf | avif
--wait <sec> no Block until done (default 60)
--async no Return without waiting
--out <file> no Save the asset when the job is done 
j2i render --payload ./job.json --out ./out.png

j2i render --template <template-id> --format png --wait 90

j2i render --payload ./job.json --async

wait

j2i wait <render-id>
j2i wait <render-id> --timeout 60

Blocks until the render finishes (or the timeout). See SSE and wait.

status

j2i status <render-id>

Fetches the current job without waiting. Same JSON as GET /api/v1/renders/{id}.

download

j2i download <render-id> --out ./out.png

--out defaults to <id>.bin. Prints { id, out, bytes, contentType } as JSON. The job must be done.

batch

j2i batch --payload ./jobs.json

--payload is required and must be { "jobs": [ ... ] }. Up to 50 jobs per batch. See Batch renders.

batch-status

j2i batch-status <batch-id>

sign

j2i sign --payload ./sign.json

--payload is required. Same JSON as signImageUrl (template, optional layers, variables, expiresIn). See URL rendering.

sign-batch

j2i sign-batch --payload ./sign-jobs.json

--payload is required and must be { "jobs": [ ... ] }. Up to 50 URLs. Does not queue renders — use batch for that.

schema

j2i schema <template-id>
j2i schema <template-id> --version 1

Lists named layers you can override in layers.

templates

j2i templates
j2i templates --project <project-id>
j2i templates --limit 50 --offset 0

Lists templates with names and descriptions so you can pick one before calling schema. Default page size is 50 (max 100).

Payload examples

Single render (--payload for render):

{
  "template": "<template-id>",
  "version": 1,
  "format": "png",
  "scale": 1,
  "transparent": false,
  "layers": {
    "headline": { "text": "Hello" }
  },
  "variables": { "plan": "pro" },
  "webhookUrl": "https://example.com/hook"
}

Batch (--payload for batch):

{
  "jobs": [
    {
      "template": "<template-id>",
      "format": "png",
      "layers": { "headline": { "text": "A" } }
    },
    {
      "template": "<template-id>",
      "format": "jpg",
      "layers": { "headline": { "text": "B" } }
    }
  ]
}

Output

  • Success responses are pretty-printed JSON on stdout.
  • With --out on render, a short Wrote … note goes to stderr (omitted when --json is set).
  • API failures print Error <status>: <message> on stderr, or { error, code, status, details } when --json is set. Exit code is 1.
j2i render --payload ./job.json --json
Previous← Code ExamplesNextErrors →