Katama API
OpenAI-compatible.

Authentication

All requests require a Bearer token in the Authorization header. Generate an API key from your billing dashboard.

Authorization: Bearer kat_live_••••••••••••••••

Base URL

All API calls go to the following base. The path structure mirrors the OpenAI API so existing SDKs require only a one-line change.

https://api.katama.ai/v1

To migrate, set base_url (Python) or baseURL (Node) to the URL above and swap your key.

Endpoints

Chat completions

Image generation

Video generation

Models

Katama routes your request to the best-fit provider. Featured models are highlighted in crimson.

Chat

Images

Video

Credit costs

Credits are deducted on each successful generation. 1 credit = €0.01. A hold is placed on submission and released if the job fails.

Code examples

The Katama API is fully OpenAI-compatible. Swap the base URL and key — your existing code works immediately.

from openai import OpenAI

client = OpenAI(
    api_key="kat_live_••••••••••••••••",
    base_url="https://api.katama.ai/v1",
)

response = client.chat.completions.create(
    model="auto",
    messages=[
        {"role": "system", "content": "You are a creative director."},
        {"role": "user", "content": "Write a tagline for a samurai-themed AI platform."},
    ],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "kat_live_••••••••••••••••",
  baseURL: "https://api.katama.ai/v1",
});

const response = await client.chat.completions.create({
  model: "claude-fable",
  messages: [{ role: "user", content: "Describe Katama in one line." }],
  stream: true,
});

for await (const chunk of response) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

curl https://api.katama.ai/v1/chat/completions   -H "Authorization: Bearer kat_live_••••••••"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-4o",
    "messages": [{ "role": "user", "content": "Hello, Katama." }]
  }'

Image generation

response = client.images.generate(
    model="flux-pro-1.1",
    prompt="A lone samurai at dawn, cinematic, 4K",
    size="1024x1024",
    quality="hd",
    n=1,
)
print(response.data[0].url)  # Signed URL, valid 24 h

Rate limits

Limits are per API key, sliding 60-second window. Exceeding returns 429 with a Retry-After header.

Video generation jobs are limited separately: 5 concurrent jobs per workspace regardless of plan.

Webhooks

Long-running jobs (video, upscale) emit webhook events so you don’t need to poll. Register a URL in the dashboard — we’ll POST to it on state transitions.

Payload shape

{
  "event": "generation.succeeded",
  "generation_id": "gen_01jxk••••",
  "kind": "video",
  "output_url": "https://cdn.katama.ai/out/••••.mp4",
  "credits_charged": 50,
  "created_at": "2025-06-09T12:00:00Z"
}

Events

Webhooks are signed with X-Katama-Signature (HMAC-SHA256). Verify against your webhook secret before processing.

Errors

The API uses standard HTTP status codes. Error bodies follow the OpenAI error shape for SDK compatibility.

{
  "error": {
    "message": "Insufficient credits. Required: 50, available: 12.",
    "type": "insufficient_credits",
    "code": 402
  }
}