Documentation

RunWeave is a unified inference API. Every image, video, audio, and 3D model is available over a single base URL with the same request shape, authenticated with one API key.

https://api.runweave.ai/api/v3

Authentication

Every request is authenticated with a Bearer API key in the Authorization header. Keep your key secret — treat it like a password and only use it from your backend.

Authorization: Bearer YOUR_API_KEY

Quickstart

Submit a generation with a POST to /{model-id}. The request returns a task you poll until it completes.

# Submit a text-to-image request
curl -X POST https://api.runweave.ai/api/v3/runweave-ai/flux-dev \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a neon koi swimming through clouds"}'

# → { "code": 200, "data": { "id": "pred_…", "status": "created", "urls": { "get": "…" } } }

Then poll the task until its status is completed:

curl https://api.runweave.ai/api/v3/predictions/PRED_ID/result \
  -H "Authorization: Bearer YOUR_API_KEY"

# → { "code": 200, "data": { "status": "completed", "outputs": ["https://…"] } }

Synchronous mode

For fast models you can skip polling and wait for the result inline by setting enable_sync_mode:

curl -X POST https://api.runweave.ai/api/v3/runweave-ai/flux-dev \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a studio portrait", "enable_sync_mode": true}'

Call from JavaScript

Any HTTP client works — here's the same submit-and-poll flow with fetch. Always call from your backend so your key stays secret.

const BASE = "https://api.runweave.ai/api/v3";
const headers = {
  Authorization: `Bearer ${process.env.RUNWEAVE_API_KEY}`,
  "Content-Type": "application/json",
};

// Submit
const submit = await fetch(`${BASE}/bytedance/seedance-2.0/text-to-video`, {
  method: "POST",
  headers,
  body: JSON.stringify({ prompt: "driving through a neon city", duration: 5 }),
}).then((r) => r.json());

// Poll until completed
let task = submit.data;
while (task.status !== "completed" && task.status !== "failed") {
  await new Promise((r) => setTimeout(r, 1000));
  task = (await fetch(`${BASE}/predictions/${submit.data.id}`, { headers }).then((r) => r.json())).data;
}
console.log(task.outputs[0]);

Call from Python

import os, time, requests

BASE = "https://api.runweave.ai/api/v3"
headers = {"Authorization": f"Bearer {os.environ['RUNWEAVE_API_KEY']}"}

submit = requests.post(
    f"{BASE}/runweave-ai/flux-dev",
    headers=headers,
    json={"prompt": "a neon koi swimming through clouds"},
).json()

task = submit["data"]
while task["status"] not in ("completed", "failed"):
    time.sleep(1)
    task = requests.get(f"{BASE}/predictions/{submit['data']['id']}", headers=headers).json()["data"]

print(task["outputs"][0])

Listing models

Browse the full catalog with GET /models. Filter by type, provider, or a free-text search, and page with limit / offset.

curl "https://api.runweave.ai/api/v3/models?type=text-to-video&search=seedance&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Or browse all 1000+ models in the catalog. Every model is priced per request — you can see the price on each model.

Buying credits

Your balance is charged per request at the model's price. Top up your balance (buy credits) through the secure Helcim checkout:

# 1. Initialize a checkout for a pack (or a custom amount_usd)
curl -X POST https://api.runweave.ai/api/v3/account/purchase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pack_id": "silver"}'

# → { "data": { "checkoutToken": "…" } }  → render the HelcimPay.js modal
# → confirm at POST /account/purchase/confirm to credit your balance

Check your balance any time with GET /balance. See the pricing tiers for how top-ups raise your rate limits.

Responses & errors

Every response uses the envelope { code, message, data }, where code mirrors the HTTP status. On success data holds the payload; on failure it is null and message explains why.