Client libraries

Three ways in: the official OpenAI SDKs for synchronous image calls (nothing to install beyond what you have), the @tokport/client TypeScript package for the queue, streaming and webhooks, and plain HTTP from anything else. Python examples use requests on every model reference page.

TypeScript client

Zero dependencies; runs in Node 18+, Bun, Deno and browsers (through the proxy below). The package lives in this repository under packages/tokport-client and is not yet on npm: install it from the repository path or vendor the src/ folder.

bash

bun add github:<your-org>/tokport#main --filter @tokport/client   # or copy packages/tokport-client/src

typescript

import { TokPort } from "@tokport/client";

const tokport = new TokPort({
  apiKey: process.env.TOKPORT_API_KEY!,
  baseUrl: "https://api.tokport.io",      // relay (/v1)
  queueUrl: "https://api.tokport.io",   // queue (/queue/v1)
});

// Synchronous: images answer inline; videos submit + poll + download for you
const image = await tokport.run("gpt-image-2", { prompt: "a neon koi", size: "1024x1024" });
console.log(image.data[0].url);

// Queue with live progress
const clip = await tokport.subscribe("seedance-2-0", { prompt: "waves at night", seconds: "5" }, {
  onQueueUpdate: (s) => console.log(s.status, s.queue_position ?? ""),
});
console.log(clip.video?.url);

// Step by step
const { request_id } = await tokport.queue.submit("gpt-image-2", { prompt: "poster" }, {
  webhookUrl: "https://example.com/tokport-hook",
  priority: "low",
});
for await (const s of tokport.queue.stream("gpt-image-2", request_id)) console.log(s.status);
const result = await tokport.queue.result("gpt-image-2", request_id, { timeout: 60 });
await tokport.queue.cancel("gpt-image-2", request_id); // 400 once it is running or done

// Discover models
const videoModels = await tokport.models.list({ modality: "video", available: true });

Errors are TokPortError with status, code, the response body and the gateway requestId when there is one. Image inputs accept await tokport.storage.toDataUrl(file).

Browser apps: keep the key on your server

The client can route every call through a same-origin endpoint that injects the key. The proxy allows only TokPort hosts and the generation paths, and streams responses (status streams included).

typescript — app/api/tokport/route.ts (Next.js)

import { createRouteHandler } from "@tokport/client/proxy";

export const { GET, POST, PUT } = createRouteHandler({
  apiKey: process.env.TOKPORT_API_KEY!,
  // allowedHosts: ["api.tokport.io", "tokport.io"] is the default
});

typescript — browser

import { TokPort } from "@tokport/client";

const tokport = new TokPort({ proxyUrl: "/api/tokport", baseUrl: "https://api.tokport.io", queueUrl: "https://api.tokport.io" });
const out = await tokport.subscribe("gpt-image-2", { prompt: "a koi" }, { onQueueUpdate: console.log });

Any framework works: createProxy(options) returns a (Request) => Promise<Response>. Add your own auth and rate limits in front of it; the proxy does not know who the browser user is.

Verify webhooks

typescript

import { verifyWebhook } from "@tokport/client";

export async function POST(req: Request) {
  const raw = await req.text();
  const event = await verifyWebhook(raw, req.headers, process.env.TOKPORT_WEBHOOK_SECRET!);
  if (!event) return new Response("bad signature", { status: 401 });
  if (event.status === "OK") console.log(event.request_id, event.payload);
  return new Response("ok");
}

The signing secret is per API key, on the keys page. Details of the payload and headers: queue docs.

OpenAI SDKs and plain HTTP

Synchronous image generation is the OpenAI images API, so the official SDKs work by changing the base URL and key; see the quickstart. Every model page generates curl, Python and JavaScript for its exact parameters, and the OpenAPI document covers the relay and queue endpoints for code generators.