Call the Percify API from Node.js, Python and cURL

Percify has no SDK package: call the REST API with fetch in Node.js, requests in Python or cURL. Copyable run, wait, estimate and error handling code.

Percify does not publish an SDK, so there is no npm or PyPI package to install. The REST API is small enough to call directly: POST /v1/run starts a job and GET /v1/generations/{id}?wait=45 returns the finished file. The code below uses the built-in fetch in Node.js 18 or newer, requests in Python, and plain cURL.

Before you start, create a key on the developer page (Scale and Ultra plans) and export it:

export PERCIFY_API_TOKEN="pk_live_…"

Generate a file and wait for it

Node.js

// percify.mjs  (Node.js 18+, no dependencies)
const API = "https://api.percify.io/v3/playground/v1";
const headers = {
  Authorization: `Bearer ${process.env.PERCIFY_API_TOKEN}`,
  "Content-Type": "application/json",
};

async function call(method, path, body, extraHeaders = {}) {
  const res = await fetch(`${API}${path}`, {
    method,
    headers: { ...headers, ...extraHeaders },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json().catch(() => null);
  if (!res.ok) {
    // Most errors are { statusCode, message, error }; 429s are a plain string.
    const message = typeof json === "string" ? json : json?.message;
    throw new Error(`Percify ${res.status}: ${message}`);
  }
  return json.data;
}

export async function generate(modelId, input, { idempotencyKey } = {}) {
  const extra = idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {};
  let gen = await call("POST", "/run", { modelId, input }, extra);
  while (gen.status !== "succeeded" && gen.status !== "failed") {
    gen = await call("GET", `/generations/${gen.id}?wait=45`);
  }
  if (gen.status === "failed") throw new Error(`Generation failed: ${gen.error}`);
  return gen; // gen.output.urls, gen.creditsSpent
}

const quote = await call("POST", "/estimate", {
  modelId: "gpt-image-2",
  input: { prompt: "Flat illustration of a paper plane", quality: "low" },
});
console.log(`This will cost ${quote.credits} credits`);

const gen = await generate(
  "gpt-image-2",
  { prompt: "Flat illustration of a paper plane", quality: "low" },
  { idempotencyKey: "paper-plane-001" },
);
console.log(gen.output.urls);

Find a model’s inputs

Each model has its own input fields. Read them from the public catalog, no key needed:

Node.js

const res = await fetch("https://api.percify.io/v3/playground/v1/models/infinitetalk-fast");
const { data } = await res.json();
console.log(data.input_schema.required, Object.keys(data.input_schema.properties));

Handle errors

Status	What to do in code
400	Fix the request. The message names the field or problem, for example Missing required field: audio or Not enough credits.
401	Check the key. It is missing, wrong, expired or revoked.
404	The generation or model id does not exist for your account.
429	Wait about a minute before retrying. The body is a JSON string such as "API key rate limit exceeded ...".
503	The model is busy and your credits were refunded. Retry with backoff.

See Errors and rate limits for every message.

Good habits

• Keep the key on your server. Browsers on other websites cannot call the API, and client code exposes the key.
• Send an Idempotency-Key on every POST /v1/run that might be retried.
• Download the files in output.urls to your own storage when you need to keep them.
• For jobs that take minutes, pass a webhook and skip the loop.

Related

Make a talking avatar video

A three-step pipeline built on these helpers.

Start a generation

Every field of POST /v1/run.

Authentication

Create, cap and revoke keys.

MCP server

Let an AI agent call Percify for you.