Images and speech

client.images.generate(...) and client.audio.speech.create(...) generate an image or synthesize speech across AnonRouter's two-origin split, in both JavaScript and Python. Parameter names follow the OpenAI API, so a working call ports over mostly unchanged.

One SDK call is two HTTP requests to two different hosts, and that is the entire point.

What each host learns

  YOU ──API key, model, size/voice, character COUNT──▶  control.anonrouter.ai
                                                         (control origin)
       ◀──────── single-use ticket, 30s ─────────────────┘

  YOU ──ticket, prompt or text─────────────────────▶  api.anonrouter.ai
                                                         (confidential origin)
       ◀──────── image bytes / audio bytes ─────────────┘

Neither host holds both halves. The control plane can say "this account paid for one 1024×1024 image" and cannot say what was in it. The confidential plane holds the prompt and cannot say whose it was.

Quickstart

The production origins are the defaults, so a key is the whole configuration.

import { writeFile } from "node:fs/promises";
import { createClient } from "@anonrouter/confidential";

const client = createClient({ apiKey: process.env.ANONROUTER_API_KEY! });

const image = await client.images.generate({
  model: "alibaba/z-image-turbo",
  prompt: "a lighthouse in a storm, painted in oils",
  size: "1024x1024",
});
await writeFile("out.png", image.data[0].bytes);
console.log(image.selected_model, image.data[0].mime_type);

const speech = await client.audio.speech.create({
  model: "venice/kokoro-text-to-speech",
  input: "The quick brown fox jumps over the lazy dog.",
  voice: "af_sky",
});
await writeFile("out.mp3", speech.audio);

curl -s https://control.anonrouter.ai/v1/models \
  -H "Authorization: Bearer $ANONROUTER_API_KEY" \
  | jq -r '.data[] | select(.model_type=="image" or .model_type=="tts") | "\(.model_type)\t\(.id)"'

The official OpenAI SDK cannot do this

This is the reason these methods exist rather than a base-URL swap.

An OpenAI client is built around one base URL and one credential. Every request it makes carries the API key to the host it is configured with. To run the exchange above it would have to send a content-free request to host A with the key, read a ticket out of the response, send the content to host B with the ticket and without the key, and bind and re-check the ticket's facts between the two. No configuration of openai — Python or Node — does that.

Both failures are the design working. The SDK methods on this page perform the exchange automatically.

Compatibility matrix

Unsupported OpenAI parameters are refused, not dropped. Silently ignoring n: 4 would hand back one image and charge for one while you believed you asked for four.

images.generate

Returns created, model, and data[] with b64_json, mime_type, and the decoded bytes (bytes in JS, data in Python).

audio.speech.create

Returns the complete audio buffer (audio) and its content_type. This endpoint returns one response body rather than a stream, and the SDK does not pretend otherwise. Python adds result.write_to(path).

Response metadata, on both

Kept because it is how you reconcile a generation against your bill.

What the ticket binds

The confidential origin independently re-derives every bound fact from the body you send and answers 409 on any drift. The SDK checks the mint's echo first, so a mismatch fails on the content-free half of the exchange and the prompt is never sent at all.

The speech character count is UTF-16 code units

Speech is priced per character, so the ticket binds the exact count and the relay rejects a body that differs by one.

AnonRouter counts UTF-16 code units. Python's len() counts code points. They disagree on every emoji and every astral-plane character: "Hi 😀" is 4 to len() and 5 to the server.

The Python SDK therefore counts UTF-16 code units, exported as utf16_length. A client that used len() would mint a ticket bound to the wrong number and get a 409 on exactly the inputs containing emoji. If you are building your own client against the raw API, this is the detail that will bite you.

Errors

Typed, with a machine-readable code and diagnostics that carry no prompt, key, or ticket. The distinction that matters is whether money moved.

Both MediaError types subclass the package's ConfidentialError, so an existing catch / except ConfidentialError keeps catching everything.

import { MediaError } from "@anonrouter/confidential";

try {
  await client.images.generate({ model, prompt });
} catch (error) {
  if (error instanceof MediaError) {
    // `provider_failed` is the only code that may correspond to work a provider
    // actually attempted and charged for.
    console.error(error.code, error.diagnostics.request_id);
    // Header values are already redacted.
    console.error(error.diagnostics.headers);
  }
}

No automatic retry

A failed media POST is never retried. A generation is billed on the provider attempt, so a transparently retried POST is a second charge for a call you made once. This holds for 500, 502, 503, 429, 408 and transport failures alike. Tickets are single-use, so a retry would fail with ticket_rejected anyway — but the rule is enforced regardless, and pinned by tests that count POSTs.

If you want to retry, do it deliberately in your own code, having decided that a duplicate generation is acceptable.

Nothing sensitive in an error

Messages and diagnostics never contain the prompt, the input text, the API key, or the ticket. Diagnostics carry the origin, path, status, the machine-readable error type, the request id, and the request headers with every credential value replaced by <redacted> — names preserved, values gone. An error body that quotes your prompt back is discarded rather than passed through. redactHeaders / redact_headers is exported so the same rule can apply to anything you log yourself.

Configuration

Two rules, both fail-closed:

• Media requires two distinct origins. If the control and inference origins are the same host, media is refused — that host would receive the API key and the prompt together, which is the exact linkage the ticket prevents. Verification and E2EE chat are unaffected, because in E2EE chat the relay receives ciphertext, so a single origin still never holds readable content.
• Two origins that disagree are refused, not resolved by precedence, and so is an origin supplied as an empty string. The ambiguity is about where prompts go.

The one documented exception is a loopback local-test override: with allowInsecureHttp / allow_insecure_http set and a loopback host, a single origin is permitted, because a developer running both roles on one machine has no privacy boundary to collapse. It cannot be reached for a remote host.

Checking the contract yourself, for free

Every claim about how the two origins behave can be checked without a key and without spending anything. These probes carry no credential and no ticket, so the relay refuses them before any provider is dispatched:

# The confidential origin serves media and fails closed without a ticket.
curl -s -X POST https://api.anonrouter.ai/v1/images/generations \
  -H 'content-type: application/json' -d '{}'
# {"error":{"message":"A single-use ticket is required","type":"ticket_required",...}}

# The control origin serves no media content at all.
curl -s -X POST https://control.anonrouter.ai/v1/audio/speech \
  -H 'content-type: application/json' -d '{}'
# {"error":{"message":"media generation is disabled","type":"media_disabled"}}

The SDK ships these as live tests. They need no key and no DCAP engine, so anyone can reproduce them:

ANONROUTER_LIVE_GATEWAY_ORIGIN=https://api.anonrouter.ai \
ANONROUTER_LIVE_PUBLIC_ORIGIN=https://control.anonrouter.ai \
  npx vitest run test/live-media.test.ts     # in js/confidential