Chat API quick start

OpenAI-compatible chat

Use one API key for chat and speech. Requests return synchronously; the live catalogue lists current model names, IDs and prices.

1. Create a key and add credits

Sign up or sign in to the console. Open API keys → Create API key, save the key shown once, then open Wallet → Add credits. A subscription is optional. API calls require a funded credit balance; creating a key does not add credits.

Keep the key on your server. See Authentication & Limits.

Local payment testing

Stripe test payments add sandbox credits only. They do not fund real model calls. For local integration testing, an administrator can top up a test user's API balance in the admin console. Live payments fund the API balance after payment confirmation.

2. Run a chat and speech example

Save the code below as chat.py. It uses Python 3's standard library, with no packages to install. Set GIRLLAB_API_KEY in your environment, then run python chat.py.

macOS / Linux

export GIRLLAB_API_KEY='sk-your-key'
python3 chat.py

Windows PowerShell

$env:GIRLLAB_API_KEY = 'sk-your-key'
python chat.py

import base64
import json
import os
from pathlib import Path
from urllib.error import HTTPError
from urllib.request import Request, urlopen

BASE = os.environ.get("GIRLLAB_API_BASE", "https://api.coldstart.win").rstrip("/")
KEY = os.environ["GIRLLAB_API_KEY"]
MODEL = os.environ.get("GIRLLAB_CHAT_MODEL")
VOICE = os.environ.get("GIRLLAB_VOICE")

def api(path, body=None):
    request = Request(
        BASE + path,
        data=json.dumps(body).encode() if body is not None else None,
        headers={"Authorization": "Bearer " + KEY,
                 "Content-Type": "application/json"},
    )
    try:
        with urlopen(request, timeout=90) as response:
            return json.load(response)
    except HTTPError as error:
        raise SystemExit(f"HTTP {error.code}: {error.read().decode()}")

catalog = api("/v1/chat/catalog")
MODEL = MODEL or catalog["defaultModel"]
VOICE = VOICE or catalog["defaultVoice"]
model = next((m for m in catalog["models"] if m["id"] == MODEL), None)
voice = next((v for v in catalog["voices"] if v["id"] == VOICE), None)
if not model or not model["available"] or not voice or not voice["available"]:
    raise SystemExit("Choose an available model and voice from /v1/chat/catalog.")

reply = api("/v1/chat/completions", {
    "model": MODEL,
    "messages": [
        {"role": "system", "content": "You are a friendly assistant."},
        {"role": "user", "content": "Say hello in one short sentence."},
    ],
    "max_tokens": 64,
})
print(json.dumps(reply, ensure_ascii=False, indent=2))
# For another turn, append the assistant reply and the next user message to messages.
print(reply["choices"][0]["message"]["content"])

speech = api("/v1/chat/speech", {"text": "Hello.", "voice": VOICE})
header, encoded = speech["audio"].split(",", 1)
file = Path("speech.mp3")
file.write_bytes(base64.b64decode(encoded))
print("Saved", file, "— speech billing:", json.dumps(speech["billing"]))

The example makes one paid text chat call and one paid speech call. It prints the chat reply, token usage and speech credits, and saves an MP3 file. Check Usage history for actual chat credits. The API base URL is https://api.coldstart.win; set GIRLLAB_API_BASE only for another deployment.

3. Try another model

Change GIRLLAB_CHAT_MODEL to chat-creative or chat-fast. Change GIRLLAB_VOICE independently:

The table below shows current public model names, model IDs and voice IDs.

Live model catalogue · credit prices

Loading model catalogue…

GET /v1/chat/catalog lists available models, all voice IDs and current prices. Use model IDs from the live catalogue, rather than the provider's upstream IDs. TTS selects its model through voice; it does not accept a chat model parameter.

Text chat: OpenAI-compatible chat. Speech and voice IDs: Speech and catalogue.

• Billing & Credits: charges, refunds and balance.
• Error Codes: authentication, balance and upstream errors.

You can also try Chat in the console. The interactive API reference lists request fields.