Viktor OpenAI-compatible API

1. Overview

Viktor exposes a compatibility API that speaks three protocols: OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages. Point any client that talks one of those protocols at the endpoint, use the model id viktor, and each request drives a real Viktor agent run.

All routes live under the prefix /api/compat, and each protocol sub-router adds its own /v1/... path. The paths are identical no matter which host you talk to, so the only thing that changes between local and deployed use is the host. See section 2 for that distinction and the endpoint table for the full list.

2. Where the endpoint lives: local vs deployed

The compat routes are mounted on Viktor's main FastAPI app, the web function fastapi_app_modal in web.py. That is the same app that serves production Viktor, so the surface behaves differently depending on how you reach it.

The deploy path is the standard Viktor one: merging to main auto-deploys dev and then staging, and production is a manual promote. PHI is refused on purpose because compat is a Standard-tier, non-PHI feature.

3. Prerequisites

• The repo checked out locally, with your work happening from backend/viktor.
• uv installed, since all Python runs go through uv run --project viktor ....
• Modal authenticated on your machine (modal token new if you have never set it up).
• For the production key pepper, the 1Password CLI (op) with vault access. For purely local dev you can instead use the built-in dev-only pepper described in section 5.

4. Start the API locally

From backend/viktor, start the served app. The web function is fastapi_app_modal.

uv run --project viktor modal serve -m viktor.main

Read the base URL from the output. Modal prints a line like the following, and the host is your base. Paste that host into the Base URL field at the top of this page.

Created web function fastapi_app_modal => https://zetalabs-ai-dev--viktor-<user>-dev.modal.run

Enable the feature flags

The compat surface is gated by feature flags and fails closed. To force-enable it locally without PostHog, add a single line to backend/viktor/.env. That file is loaded into the Modal container as a dotenv secret.

VIKTOR_AGENT_BENCH_FEATURE_FLAGS={"compat_api": true, "compat_api_chat_completions": true, "compat_api_responses": true, "compat_api_messages": true}

5. Create an API key

You need a personal API key with the scope chat:completions. Two facts matter before you mint one.

• Identity requirement. The key's actor_user_id must be a real user that has a linked Slack identity. Auth can pass and the run will still be denied at identity resolution if that link is missing.
• Pepper match. Key hashing uses a pepper. The minting process and the running server must share the same pepper, or the key will never validate.

Pepper options

• Production pepper. Pull API_KEY_PEPPER_V1 from the vault into your env file: op inject -i backend/viktor/.env.1password >> backend/viktor/.env.
• Dev-only pepper. For purely local dev, set APP_ENV=dev and ALLOW_INSECURE_API_KEY_PEPPER=true to use the built-in dev pepper. Both the mint step and the server must have these set.

Where to run the mint

Save this as backend/viktor/viktor/mint_compat_key.py.

import asyncio

from db.db import PublicApiKeyDBModel
from viktor.apis.public_api.security import (
    generate_public_api_key,
    get_current_scope_registry_version,
)
from viktor.db_ops.public_api_db_ops import create_public_api_key_db

# A real user id that has a linked Slack identity. Without the Slack link
# the run is denied at identity resolution even though auth succeeds.
ACTOR_USER_ID = "user_replace_me"


async def main() -> None:
    raw_key, public_id, key_preview, secret_hash, pepper_version = (
        generate_public_api_key()
    )
    api_key = PublicApiKeyDBModel(
        name="compat-quickstart",
        key_type="personal",
        team_id=None,
        actor_user_id=ACTOR_USER_ID,
        created_by_user_id=ACTOR_USER_ID,
        public_id=public_id,
        key_preview=key_preview,
        secret_hash=secret_hash,
        pepper_version=pepper_version,
        scopes=["chat:completions"],
        scope_registry_version=get_current_scope_registry_version(),
    )
    await create_public_api_key_db(api_key)
    # The raw key is returned only once. Only its hash is stored.
    print("RAW KEY (copy now, shown once):", raw_key)


if __name__ == "__main__":
    asyncio.run(main())

Run it in a container that shares the app spec, from backend/viktor.

uv run --project viktor modal shell -m viktor.main::fastapi_app_modal -c 'python -m viktor.mint_compat_key'

6. Try it out (live)

This panel sends a real request from your browser using the Base URL and API key from the top of the page. Pick an endpoint, edit the payload if you want, and press Send. The equivalent curl command is always shown below so you have a guaranteed path from a terminal.

No request sent yet.

7. curl

Export your base and key once, then reuse them. Both Authorization: Bearer <key> and x-api-key: <key> are accepted on every compat endpoint. If you send both, x-api-key wins.

export VIKTOR_BASE_URL="{{BASE_URL}}"
export VIKTOR_API_KEY="{{API_KEY}}"

Liveness check: list models

curl "$VIKTOR_BASE_URL/api/compat/v1/models" \
  -H "Authorization: Bearer $VIKTOR_API_KEY"

Chat Completions, non-streaming

curl "$VIKTOR_BASE_URL/api/compat/v1/chat/completions" \
  -H "Authorization: Bearer $VIKTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viktor",
    "messages": [{"role": "user", "content": "Say hello in one sentence."}]
  }'

Chat Completions, streaming

curl -N "$VIKTOR_BASE_URL/api/compat/v1/chat/completions" \
  -H "Authorization: Bearer $VIKTOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viktor",
    "stream": true,
    "messages": [{"role": "user", "content": "Stream a short greeting."}]
  }'

Anthropic Messages

The Anthropic surface requires max_tokens and conventionally uses the x-api-key header.

curl "$VIKTOR_BASE_URL/api/compat/v1/messages" \
  -H "x-api-key: $VIKTOR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "viktor",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Say hello in one sentence."}]
  }'

8. Python OpenAI SDK

The OpenAI Python SDK reads OPENAI_BASE_URL and OPENAI_API_KEY from the environment automatically, so the env-var setup is the shortest path.

export OPENAI_BASE_URL="{{OPENAI_BASE}}"
export OPENAI_API_KEY="{{API_KEY}}"

Non-streaming (env vars)

from openai import OpenAI

# Reads OPENAI_BASE_URL and OPENAI_API_KEY from the environment.
client = OpenAI()

resp = client.chat.completions.create(
    model="viktor",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(resp.choices[0].message.content)

Explicit constructor arguments (alternative)

from openai import OpenAI

client = OpenAI(
    base_url="{{OPENAI_BASE}}",
    api_key="{{API_KEY}}",
)

Streaming

stream = client.chat.completions.create(
    model="viktor",
    messages=[{"role": "user", "content": "Stream a short greeting."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
print()

9. TypeScript OpenAI SDK

The Node SDK also reads OPENAI_BASE_URL and OPENAI_API_KEY automatically.

export OPENAI_BASE_URL="{{OPENAI_BASE}}"
export OPENAI_API_KEY="{{API_KEY}}"

Non-streaming (env vars)

import OpenAI from "openai";

// Reads OPENAI_BASE_URL and OPENAI_API_KEY from the environment.
const client = new OpenAI();

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

Explicit constructor arguments (alternative)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "{{OPENAI_BASE}}",
  apiKey: "{{API_KEY}}",
});

Streaming

const stream = await client.chat.completions.create({
  model: "viktor",
  messages: [{ role: "user", content: "Stream a short greeting." }],
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}
process.stdout.write("\n");

10. Agentic harness configuration

Each harness below is pointed at your host with model id viktor. For OpenAI-protocol harnesses the base is {HOST}/api/compat/v1. For Claude Code the base is the Anthropic surface described in its section. All snippets reflect the fields at the top of the page.

Every subsection leads with the environment-variable method and falls back to a config file only where the tool genuinely needs one. In practice Claude Code is fully env-configurable, while Codex, OpenCode, and Pi can take the API key from an env var but still require a small config-file entry to select a custom base URL. Where a config file is required, it is shown as a clearly labeled secondary step and always pulls the key from an env var rather than hardcoding it.

export VIKTOR_API_KEY="{{API_KEY}}"

{
  "providers": {
    "viktor": {
      "baseUrl": "{{OPENAI_BASE}}",
      "api": "openai-completions",
      "apiKey": "$VIKTOR_API_KEY",
      "authHeader": true,
      "models": [
        { "id": "viktor", "name": "Viktor" }
      ]
    }
  }
}

pi --provider viktor --model viktor
# verify the provider loaded:
pi --list-models viktor

export VIKTOR_API_KEY="{{API_KEY}}"

{
  "$schema": "https://opencode.ai/config.json",
  "model": "viktor/viktor",
  "provider": {
    "viktor": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Viktor",
      "options": {
        "baseURL": "{{OPENAI_BASE}}",
        "apiKey": "{env:VIKTOR_API_KEY}"
      },
      "models": {
        "viktor": { "name": "Viktor" }
      }
    }
  }
}

export VIKTOR_API_KEY="{{API_KEY}}"

model = "viktor"
model_provider = "viktor"

[model_providers.viktor]
name = "Viktor"
base_url = "{{OPENAI_BASE}}"
env_key = "VIKTOR_API_KEY"
wire_api = "responses"
requires_openai_auth = false

codex

export ANTHROPIC_BASE_URL="{{ANTHROPIC_BASE}}"
export ANTHROPIC_API_KEY="{{API_KEY}}"
export ANTHROPIC_MODEL="viktor"
export ANTHROPIC_SMALL_FAST_MODEL="viktor"
claude

Endpoint reference

All paths are relative to your host, whether that is a local modal serve URL or a deployed Viktor API host. Every endpoint requires the scope chat:completions and accepts either Authorization: Bearer or x-api-key.

11. Troubleshooting and gotchas