API CONTRACT

Change the base URL. Keep the client.

Tsubasa implements model discovery and OpenAI-compatible Chat Completions. Use a Tsubasa key and a model ID returned by the current catalog.

Get API access Browse models

https://api.tsubasa.sh/v1

Authentication: Bearer key
Streaming: SSE
Key prefix: ts_live_

GET

/v1/models

Returns the enabled model IDs for the current environment in an OpenAI-style list envelope.

POST

/v1/chat/completions

Accepts multi-message chat requests and returns either one JSON completion or server-sent event chunks.

model: required string
messages: 1–256 text messages
temperature: 0–2; default 1
max_tokens: positive integer; default 512
stream: boolean; default false
stop: string or up to four strings
stream_options: include_usage boolean
roles: system, user, assistant

CLIENT EXAMPLES

Use the interface your application already knows.

The JavaScript example is covered by the repository’s official client test. Python follows the official client’s custom base URL interface and remains Experimental until its own automated contract test is added.

JavaScript SDK · Verifiedtypescript

import OpenAI from "openai"

const client = new OpenAI({
  apiKey: process.env.TSUBASA_API_KEY,
  baseURL: "https://api.tsubasa.sh/v1",
})

const stream = await client.chat.completions.create({
  model: "tsubasa-medium",
  messages: [
    { role: "system", content: "Be precise and concise." },
    { role: "user", content: "Review this repository and propose a patch." },
  ],
  max_tokens: 512,
  temperature: 0.7,
  stream: true,
})

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

Python SDK · Experimentalpython

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TSUBASA_API_KEY"],
    base_url="https://api.tsubasa.sh/v1",
)

stream = client.chat.completions.create(
    model="tsubasa-medium",
    messages=[
        {"role": "system", "content": "Be precise and concise."},
        {"role": "user", "content": "Review this repository."},
    ],
    max_tokens=512,
    temperature=0.7,
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

Direct HTTPshell

curl https://api.tsubasa.sh/v1/chat/completions \
  -H "Authorization: Bearer $TSUBASA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tsubasa-medium",
    "messages": [{"role": "user", "content": "Explain this code."}],
    "max_tokens": 512,
    "temperature": 0.7,
    "stream": false
  }'

Streaming and cancellation

Streamed responses use server-sent events.
Set stream_options.include_usage to receive terminal usage.
Confirmed cancellation settles available usage and releases concurrency; uncertain provider stop keeps both reservations until bounded expiry.

Authentication and accounting

Send a ts_live_ key as an Authorization bearer token.
Legacy op_live_ keys remain valid until revoked.
Each admitted request reserves credit and settles against actual terminal usage.

Model capability labels are separate from transport support. A working Chat Completions endpoint does not prove tool calling, structured output, vision, or coding quality; check the canonical model definition before relying on those behaviors.