Zero-dependency Node.js client for the HiAPI unified async task API (/v1/tasks) — submit an image / video / audio generation task, poll it to completion, and read the output in one call.
- Zero runtime dependencies. Built on the global
fetchandnode:crypto— nothing else. - One-call workflow.
client.tasks.run(...)submits and waits for you. - TypeScript-first. Full type declarations, ESM and CommonJS entry points.
- Webhook verification. HMAC-SHA256 signature + timestamp freshness check, built in (still deduplicate deliveries by task id).
For OpenAI-compatible chat/image endpoints, keep using the
openailibrary withbaseURL: "https://api.hiapi.ai/v1". This SDK focuses on what the OpenAI client can't do: the asynchronous submit → poll → retrieve lifecycle (results come back as output URLs).
npm install hiapiRequires Node.js 18.17+. On Node 18–20, the first request prints a one-time
ExperimentalWarning: The Fetch API is an experimental feature to stderr —
this comes from Node's own global fetch (stable since Node 21), not from
this package, and is harmless.
import { HiAPI } from "hiapi";
// CommonJS works too: const { HiAPI } = require("hiapi");
const client = new HiAPI({ apiKey: "sk-..." }); // or set HIAPI_API_KEY
const task = await client.tasks.run({
model: "seedance-2-0",
input: { prompt: "a cyan glass data center entrance", resolution: "1080p" },
onUpdate: (t) => console.log("status:", t.status),
});
for (const out of task.output) {
console.log(out.type, out.url); // e.g. "video https://cdn.hiapi.ai/tasks/..."
}run() resolves once the task reaches a terminal state. It throws
TaskFailedError if the task fails and PollTimeoutError once the
timeoutMs polling budget (default 600000 — 10 minutes) is used up — checked
between polls, not a hard cutoff, so a slow individual request can push the
actual wait somewhat past timeoutMs. A poll timeout does not cancel the
task — it may still finish (and bill) later; take taskId from the
PollTimeoutError and retrieve() it instead of submitting the same request
again.
timeoutMs does not bound onUpdate itself for the final (success/
fail) call — by the time the task reaches a terminal state, the SDK already
has the real result in hand, and there's no safe way to give up on an
in-flight onUpdate call without either hanging anyway or silently
discarding whatever it was doing (e.g. persisting the result). It's awaited
to completion instead. If your onUpdate does work that could itself hang,
bound it with signal:
const task = await client.tasks.run({
model: "seedance-2-0",
input: { prompt: "..." },
signal: AbortSignal.timeout(120_000), // also bounds a hanging onUpdate
onUpdate: async (t) => {
await saveTaskState(t); // if this hangs, `signal` is what stops the wait
},
});Aborting stops wait()/run() from waiting any further — it does not
cancel the remote task, or any onUpdate call already in progress.
Output URLs are temporary — they expire about 7 days after creation (each
output carries expireAt). To keep an output long-term, pass
storage: "persistent" to create()/run() (billed by size; insufficient
balance or exceeding your storage cap silently downgrades to "temp" — the
actual tier used is echoed back as task.storage), or promote it after the
fact — see the Output Storage docs.
const created = await client.tasks.create({
model: "seedance-2-0",
input: { prompt: "...", resolution: "720p" },
callback: { url: "https://your-app.com/hiapi/callback", when: "final" },
});
console.log(created.taskId);
let task = await client.tasks.retrieve(created.taskId); // one status check
task = await client.tasks.wait(created.taskId, { pollIntervalMs: 3000, timeoutMs: 900000 });
const page = await client.tasks.list({ page: 1, size: 20 }); // newest firstinput fields are defined per model — see the relevant
model page. Don't put callback fields inside
input; pass callback separately.
Some models expose multiple routes (e.g. ext) with different pricing or
upstream capacity. Pass route instead of writing the model@route suffix:
const created = await client.tasks.create({
model: "gpt-image-2/text-to-image",
route: "ext", // preferred over model: "...@ext"
input: { prompt: "..." },
});Omitting route (or passing "default") uses the model's default route. An
unknown route fails fast with a 400 whose message lists the available routes.
The legacy model: "x@ext" spelling keeps working. When a task was submitted
with route, its detail echoes task.route and task.model holds the
resolved full name (x@ext).
Pass idempotencyKey (sent as the Idempotency-Key header — printable ASCII,
≤255 characters) to make task submission safe to retry — retrying the same
key + same body within about 24 hours returns the first task instead of
creating and billing a new one (after that the key is cleaned up and the same
request creates a new task):
const created = await client.tasks.create({
model: "seedance-2-0",
input: { prompt: "..." },
idempotencyKey: "order-8472:video", // a stable key you derive per job
});
if (created.idempotentReplay) {
console.log("hit the idempotency cache; no new task created");
}With a key set, the SDK also retries the POST on network errors and retries
409 IDEMPOTENCY_KEY_PROCESSING (the first request is still in flight) up to
the retry limit (default 2), honouring Retry-After capped at 60s. Reusing a
key with a different body throws IdempotencyKeyMismatchError — that's a
key-construction bug, not retryable.
If you set a Webhook signing key in the HiAPI console, terminal callbacks are signed. Verify them against the raw request body:
import { createServer } from "node:http";
import { HiAPI, WebhookVerificationError } from "hiapi";
const client = new HiAPI({ apiKey: "sk-...", webhookSecret: "whsec_..." });
const MAX_BODY = 1024 * 1024; // 1 MiB — reject oversized bodies before verifying
createServer((req, res) => {
if (req.method !== "POST" || req.url !== "/hiapi/callback") {
res.writeHead(404).end();
return;
}
const chunks = [];
let size = 0;
req.on("data", (chunk) => {
size += chunk.length;
if (size > MAX_BODY) {
res.writeHead(413).end();
req.destroy();
return;
}
chunks.push(chunk);
});
req.on("end", () => {
let task;
try {
task = client.webhooks.verify(Buffer.concat(chunks), req.headers);
} catch (err) {
if (err instanceof WebhookVerificationError) {
res.writeHead(400).end();
return;
}
throw err;
}
if (task.succeeded && task.output.length > 0) {
console.log(task.output[0].url);
}
res.writeHead(200).end(); // ack with 2xx; HiAPI retries non-2xx
});
}).listen(3000);If you use a framework, make sure the handler receives the exact bytes of
the request body (e.g. express.raw({ type: "application/json" }) in Express)
— verifying a re-serialized JSON object can fail even when the payload is
legitimate.
Callbacks are delivered at least once and can arrive concurrently — make
your handler idempotent (e.g. upsert your own record keyed by task.taskId)
and return 2xx only after processing succeeds. Duplicates are then harmless,
and a failed or crashed handler is simply redelivered.
| Error class | When |
|---|---|
AuthenticationError |
401 — bad/missing API key |
NotFoundError |
404 — unknown task or not yours |
InvalidRequestError |
INVALID_REQUEST — fix the request |
ModelUnavailableError |
MODEL_UNAVAILABLE — retry or switch model |
TaskFailedSyncError |
TASK_FAILED — the submission was rejected synchronously (distinct from TaskFailedError below) |
TaskTimeoutError / StorageUnavailableError |
retryable upstream errors |
ServiceUnavailableError |
503 — platform busy (auto-retried) |
IdempotencyKeyProcessingError |
409 — same key still in flight (auto-retried; retryable) |
IdempotencyKeyMismatchError |
422 — key reused with a different body (not retryable) |
APIError |
any other non-2xx response (base class — e.g. 402, 403; carries status and body) |
APIConnectionError |
network failure or client-side timeout (auto-retried for reads only — not a keyless create()) |
TaskFailedError |
a polled task ended in status=fail (carries task and code) |
PollTimeoutError |
run()/wait() exceeded its timeout (carries taskId) |
RunAbortedError |
run()'s signal was aborted right after its task was created (carries taskId — the task exists and may still bill) |
RunFailedError |
run()'s task exists but failed some other way while polling — network/API error, an onUpdate rejection, a later abort (carries taskId and the original error as cause) |
WebhookVerificationError |
bad signature or stale timestamp |
429/503 are retried automatically with exponential backoff (maxRetries,
default 2; honours Retry-After). Network errors are retried only for
idempotent GETs (retrieve / list, and the polling inside wait / run).
The POST that create() issues is never retried on a network failure —
unless you pass idempotencyKey, which makes the retry safe server-side.
Without a key, an APIConnectionError from create() leaves the request in an
unknown state — a task may or may not have been created (and billed).
list() can help you inspect recent tasks manually, but tasks don't echo your
input back, so absence from the list doesn't prove the request failed — don't
retry automatically on that basis. For anything automated, submit with an
idempotencyKey so the retry is safe by design.
new HiAPI({
apiKey: undefined, // falls back to HIAPI_API_KEY
baseUrl: "https://api.hiapi.ai/v1",
timeoutMs: 60_000, // per-request
maxRetries: 2,
webhookSecret: undefined, // falls back to HIAPI_WEBHOOK_SECRET
fetch: undefined, // custom fetch impl (testing/instrumentation)
});This SDK is designed for server-side use. Don't ship your API key to browsers — route generation through your backend instead.
MIT