One API for text, images, audio and media models

Tokza account sessions and Tokza API keys are different credentials. Use the account portal to create, name, limit and revoke API keys. Send an API key only in the HTTPS Authorization header; never put it in a browser bundle, source repository, URL or prompt.

1. 1
   Create an account

   Register at api.tokza.ai/register or sign in.

2. 2
   Create a scoped API key

   Use a clear name, the smallest necessary access, and an account/workspace spend limit where available.

3. 3
   Store it server-side

   Load it from a protected secret manager or environment variable and rotate it after suspected exposure.

Authorization: Bearer $TOKZA_API_KEY

Call GET /v1/models first and select a model returned to your key. The examples use gpt-4o-mini only as an illustrative model observed in the public catalog on August 14, 2026.

curl https://api.tokza.ai/v1/chat/completions \
  -H "Authorization: Bearer $TOKZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Say hello in one sentence."}]
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKZA_API_KEY"],
    base_url="https://api.tokza.ai/v1",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOKZA_API_KEY,
  baseURL: "https://api.tokza.ai/v1",
});

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});
console.log(response.choices[0].message.content);

Common response envelope

For Chat Completions, read generated text from choices[0].message.content. Store the response id, selected model, and usage fields when returned; exact usage fields can vary by route.

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "model": "gpt-4o-mini",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Hello from Tokza."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 14, "completion_tokens": 5, "total_tokens": 19}
}

The primary integration surface is the OpenAI-compatible base below. Do not append a second /v1 when an SDK accepts a complete base URL.

Model names, availability and supported formats change. Make GET /v1/models part of onboarding and cache the result briefly rather than shipping a permanent list.

curl https://api.tokza.ai/v1/models \
  -H "Authorization: Bearer $TOKZA_API_KEY"

Catalog-declared On August 14, 2026, the public catalog contained labels for OpenAI, Responses, Anthropic, Gemini, image generation/editing, speech, embeddings, rerank, realtime and asynchronous media. Treat those labels as routing hints and validate a capped request before production.

Send an ordered messages array. Common roles are system, user, assistant and tool, but accepted fields and limits depend on the selected model.

{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "system", "content": "Answer concisely."},
    {"role": "user", "content": "Give me three names for an analytics feature."}
  ],
  "temperature": 0.3,
  "max_tokens": 120
}

Use Responses only with a model marked openai-response. Its input/output items differ from Chat Completions; do not assume choices[0] exists.

curl https://api.tokza.ai/v1/responses \
  -H "Authorization: Bearer $TOKZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Explain exponential backoff in 50 words."
  }'

Standard-compatible For compatible routes, set stream: true and consume Server-Sent Events until the terminal event. Event payloads differ between Chat Completions and Responses.

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Write a two-line poem."}],
    stream=True,
)

for event in stream:
    delta = event.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

• Treat a connection close before a terminal event as incomplete.
• Do not automatically replay a request after partial output when duplicate spend or side effects matter.
• Record request ID, model, attempt number and whether a terminal usage record arrived.
• For multi-turn Chat Completions, your application owns the message history and token budget.

Realtime sessions

The public catalog maps its realtime capability to this route. Before adoption, confirm the authenticated session bootstrap, transport, ephemeral-key policy, event names, audio formats and termination behavior for the selected model. A catalog path alone does not establish a WebSocket or WebRTC contract.

Standard-compatible Tool calling and JSON-schema output are model-dependent. Validate support with the selected model and never execute tool arguments without application authorization and schema validation.

{
  "model": "gpt-4o-mini",
  "messages": [{"role": "user", "content": "Weather in Rome?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Return current weather for one city",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
        "additionalProperties": false
      }
    }
  }]
}

Validate the tool name and arguments, enforce per-user authorization, execute the function in your application, then send a tool-result message tied to the returned call ID. Model selection is not permission to perform the action.

Conditional Use image content only with a model whose account-visible contract supports vision. Prefer short-lived HTTPS URLs or accepted data URLs, and do not assume every OpenAI-compatible chat model accepts image parts.

{
  "model": "<VISION_MODEL_FROM_V1_MODELS>",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "Describe the chart."},
      {"type": "image_url", "image_url": {"url": "https://example.com/chart.png"}}
    ]
  }]
}

Confirm accepted MIME types, size limits, URL-fetch policy, detail controls and retention before sending sensitive media.

curl https://api.tokza.ai/v1/embeddings \
  -H "Authorization: Bearer $TOKZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<EMBEDDING_MODEL_FROM_V1_MODELS>","input":["First document","Second document"]}'

Store the exact model ID and vector dimension with every embedding batch. Do not mix vectors from different models or silent model revisions in one index.

The public catalog maps rerank-labelled models to /v1/rerank. Confirm the selected model’s document/query fields, maximum document count, score direction and response schema; test ranking order on a fixed fixture before production.

curl https://api.tokza.ai/v1/images/generations \
  -H "Authorization: Bearer $TOKZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<IMAGE_MODEL_FROM_V1_MODELS>",
    "prompt": "A clean isometric diagram of an API gateway",
    "size": "1024x1024"
  }'

Response format, size options, moderation, input images, masks, edit endpoints and URL expiry are model-specific. Download generated assets promptly and retain provider/model/request metadata needed for audits.

Catalog-declared Tokza’s public catalog included speech-to-text, text-to-speech, synchronous speech and asynchronous speech labels. Exact model, voice, file-size and format support must be confirmed per account.

curl https://api.tokza.ai/v1/audio/transcriptions \
  -H "Authorization: Bearer $TOKZA_API_KEY" \
  -F "model=<TRANSCRIPTION_MODEL_FROM_V1_MODELS>" \
  -F "file=@meeting.mp3"

curl https://api.tokza.ai/v1/audio/speech \
  -H "Authorization: Bearer $TOKZA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<TTS_MODEL_FROM_V1_MODELS>","voice":"<SUPPORTED_VOICE>","input":"Hello from Tokza."}' \
  --output speech.mp3

Do not log raw audio by default. Validate consent, voice rights, accepted formats, maximum duration and retention before uploading customer recordings.

Catalog-declared The public catalog included model-level anthropic and gemini labels. Those labels do not mean all Tokza models accept native provider SDKs or preserve every provider-specific field.

Conditional Video, music and some image/audio models use submit-and-poll workflows. Tokza’s catalog declares multiple media formats, but task paths, status values, callback signatures and cancellation rules vary by model family.

Never assume a timeout means the task failed. A create request can complete upstream after your connection closes; query the known task or reconcile account usage before creating another.

Any client that accepts an OpenAI-compatible base URL and bearer key can be evaluated with Tokza. Support still depends on the specific endpoints and fields that client uses.

TOKZA_API_KEY=<TOKZA_API_KEY>
OPENAI_API_BASE=https://api.tokza.ai/v1
OPENAI_BASE_URL=https://api.tokza.ai/v1

Use the HTTP status and structured error type as the primary control signal. Preserve Tokza’s request identifier from errors and response headers when available; human-readable messages may be localized or change.

for attempt in range(4):
    try:
        return call_tokza()
    except RateLimitError as error:
        wait = error.retry_after or min(8, 2 ** attempt)
        sleep(wait + random.uniform(0, 0.25))
    except (BadRequestError, AuthenticationError, PermissionDeniedError):
        raise
raise RuntimeError("Tokza retry budget exhausted")

Apply an end-to-end deadline shorter than your user-facing timeout. Do not stack SDK retries, proxy retries and application retries without one shared attempt budget.

Content moderation

Tokza’s catalog maps a moderation capability to this route. Confirm which moderation model is available, the category/score schema and whether media is supported. Moderation is one control layer; keep application authorization, abuse monitoring and human escalation for consequential decisions.

Documentation evidence reviewed August 14, 2026. Model availability and account contracts can change; authenticated discovery wins over this dated guide.