@runapi.ai/flux-kontext — RunAPI.ai Flux Kontext image generation

Build Node / TypeScript integrations that generate and transform images through RunAPI.ai.

Setup

Requires Node 18+ (global fetch).

npm install @runapi.ai/flux-kontext

Set your API key in the environment:

# .env
RUNAPI_API_KEY=runapi_xxx   # get one at https://runapi.ai/api_keys

import { FluxKontextClient } from '@runapi.ai/flux-kontext';

// The SDK reads RUNAPI_API_KEY from the environment automatically.
const client = new FluxKontextClient();

Pass { apiKey } explicitly if you manage secrets differently. baseUrl defaults to https://runapi.ai; override only for local development.

Core recipe — text to image

const result = await client.textToImage.run({
  model: 'flux-kontext-pro',
  prompt: 'A futuristic cityscape at night',
  aspect_ratio: '16:9',
  output_format: 'jpeg',
});

const url = result.images[0].url;

run() creates the task, auto-polls, and resolves only when the task completes — images[0].url is populated on success. On failure it throws TaskFailedError; on polling timeout it throws TaskTimeoutError. Use run() for scripts and short-lived processes. For request handlers, split it:

const { id } = await client.textToImage.create({ model: 'flux-kontext-pro', prompt: '...' });
// return 202 immediately; fetch later:
const status = await client.textToImage.get(id);
if (status.status === 'completed') { /* ... */ }

Do not hold a web worker open waiting on run(). Split + webhook is the production pattern.

run() polls every 2 s for up to 15 min by default. Tune when needed:

await client.textToImage.run(params, { maxWaitMs: 5 * 60_000, pollIntervalMs: 2_000 });

If TaskTimeoutError fires, the task is still running server-side — resume with textToImage.get(id) or finish via webhook.

Image-to-image — edit a source image

Pass input_image (a single URL) along with your prompt:

await client.textToImage.run({
  model: 'flux-kontext-max',
  prompt: 'Restyle as a 1970s film photograph',
  input_image: 'https://cdn.example.com/source.jpg',
  aspect_ratio: '4:3',
});

Models

aspect_ratio values: 21:9, 16:9, 4:3, 1:1, 3:4, 9:16. output_format: jpeg / png.

Exact credit costs per model are shown at https://runapi.ai/pricing and in the dashboard — do not hardcode prices in application code.

Callbacks (webhooks)

Pass callback_url on create() (or any run() call) and RunAPI will POST the final payload to you:

await client.textToImage.create({
  model: 'flux-kontext-pro',
  prompt: '...',
  callback_url: 'https://your.app/webhooks/runapi/flux-kontext',
});

Payload shape:

{ id: string; status: 'completed' | 'failed'; images?: { url: string; origin_url?: string }[]; error?: string }

Always verify the signature before trusting the body. RunAPI signs every callback with your account's Callback Secret (rotate at /accounts/callback_secret). Headers:

• X-Callback-Id — UUID, store to make handler idempotent
• X-Callback-Timestamp — unix seconds, reject if |now - ts| > 300
• X-Callback-Signature — base64 HMAC-SHA256 over `${id}.${ts}.${rawBody}` using the base64-decoded secret

import crypto from 'node:crypto';

function verify(raw: string, id: string, ts: string, sig: string, secret: string) {
  const key = Buffer.from(secret, 'base64');
  const mac = crypto.createHmac('sha256', key)
    .update(`${id}.${ts}.${raw}`)
    .digest('base64');
  return crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(sig));
}

Reply 2xx within 10s; any non-2xx triggers retries.

Errors

All errors are re-exported from @runapi.ai/core. Always instanceof — never string-match messages.

import { InsufficientCreditsError, TaskFailedError } from '@runapi.ai/flux-kontext';

try {
  await client.textToImage.run({ model: 'flux-kontext-pro', prompt: '...' });
} catch (err) {
  if (err instanceof InsufficientCreditsError) { /* surface top-up CTA */ }
  else if (err instanceof TaskFailedError)       { /* show err.details */ }
  else throw err;
}

Gotchas

• model is required on every call.
• input_image is a single URL (string), not an array — this is the one endpoint in the family that takes a scalar URL.
• enable_translation defaults to true — the prompt is auto-translated to English. Set false to keep the raw prompt.
• callback_url must be reachable from the public internet. localhost / 127.0.0.1 URLs will never fire — use a tunnel (cloudflared, ngrok, tailscale funnel) when developing locally.

Dig deeper

Package README (full API surface, all params): node_modules/@runapi.ai/flux-kontext/README.md. Types: @runapi.ai/flux-kontext/dist/types.d.ts. Product docs: https://runapi.ai/docs.

RunAPI public routing

flux kontext api public links use the API-379 catalog route map. The main flux kontext api page is https://runapi.ai/models/flux-kontext. SDK docs live at https://runapi.ai/docs#sdk-flux-kontext and product docs live at https://runapi.ai/docs#flux-kontext.

Pricing, rate limits, and commercial usage for flux kontext api should point to the most specific variant page:

• Flux Kontext Pro
• Flux Kontext Max

Compare Flux Kontext with other Black Forest Labs models at https://runapi.ai/providers/black-forest-labs. Browse every RunAPI model and skill at https://runapi.ai/models. SDK repository: https://github.com/runapi-ai/flux-kontext-sdk. Skill repository: https://github.com/runapi-ai/flux-kontext.