TycoonRouter API

Developer docs

Use one authentication, idempotency and error contract from first request through production billing.

Base URL: https://router.tycoon.cool · All authenticated requests use Authorization: Bearer tr_live_….

Authentication

Create an independent TycoonRouter account, then keep the generated API key in a server-side secret manager. Never expose it in browser code or source control.

export TYCOONROUTER_API_KEY="tr_live_…"
export TYCOONROUTER_BASE_URL="https://router.tycoon.cool"

First request

import os, requests, uuid

response = requests.post(
    "https://router.tycoon.cool/v1/run",
    headers={
        "Authorization": f"Bearer {os.environ['TYCOONROUTER_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "model": "qwen/qwen3.5-flash",
        "inputs": {"messages": [{"role": "user", "content": "Hello"}]},
    },
    timeout=120,
)
response.raise_for_status()
print(response.json())

Endpoints

Method	Path	Purpose
POST	/v1/run	Unified chat, search, media and async request
POST	/v1/chat/completions	OpenAI-compatible chat
POST	/v1/messages	Anthropic-compatible messages
GET	/v1/models	Authenticated catalog
GET	/v1/usage	Settled usage records

Idempotency

Give each non-read-only request a unique Idempotency-Key. Reusing a key with the same body returns the first result. Reusing it with a different body fails with a conflict.

Do not retry a paid request with a new idempotency key after a timeout. First query its request or job status.

Billing

TycoonRouter reserves the maximum bounded retail amount before dispatch, settles the known actual amount after success, and releases the remainder. Failed pre-dispatch requests are not charged.

Errors

Code	Meaning
invalid_credentials	Missing, invalid or revoked API key
insufficient_balance	Wallet cannot cover the bounded reserve
provider_cost_unknown	Provider result cannot be settled safely
idempotency_conflict	Key was reused with a different request body

Choose capability Open in console