API reference

TaiKhoanGiaRe exposes one REST API for language, image, video and voice models. It follows the OpenAI and Anthropic wire formats, so existing SDKs work by changing the base URL.

Quickstart

Three steps, about two minutes. Everything below uses your key in the TKGR_KEY environment variable.

# macOS / Linux
export TKGR_KEY="sk-tk-..."

# Windows PowerShell
setx TKGR_KEY "sk-tk-..."

1. Check that the key works. This costs nothing and returns your balance.

curl https://taikhoangiare.vn/v1/account -H "Authorization: Bearer $TKGR_KEY"

2. Send your first message.

curl https://taikhoangiare.vn/v1/chat/completions \
  -H "Authorization: Bearer $TKGR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-5", "messages": [{"role": "user", "content": "Hello!"}]}'

3. Point an official SDK at us. Only the base URL and key change — the rest of your code stays as it is.

# Python
pip install openai

from openai import OpenAI
client = OpenAI(base_url="https://taikhoangiare.vn/v1", api_key="sk-tk-...")
r = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(r.choices[0].message.content)
print(r.usage)          # prompt_tokens, completion_tokens, total_tokens

// Node.js
npm i openai

import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://taikhoangiare.vn/v1", apiKey: "sk-tk-..." });
const r = await client.chat.completions.create({
  model: "claude-sonnet-5",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(r.choices[0].message.content);

Authentication

Every request needs your secret key. Send it in either header:

Authorization: Bearer sk-tk-...
# or
x-api-key: sk-tk-...

Keep keys server-side. If a key leaks, roll it from the dashboard — the old key stops working immediately.

Credits & billing

Everything is paid from one prepaid balance. 1 credit = 50đ. New accounts start with 50 free credits.

Failed or empty responses cost nothing. Reserved credits for a failed image or video job return to your balance automatically — you do not need to ask.

Token counts come back in every language-model response under usage, and every request is listed with its exact credit cost in Dashboard → Usage, exportable as CSV.

Models

Model IDs are listed live. Use them exactly as returned.

Browse them visually in the model catalog.

Chat Completions

OpenAI-compatible. Supports messages, temperature, max_tokens, tools, image inputs (on vision models) and stream.

from openai import OpenAI

client = OpenAI(base_url="https://taikhoangiare.vn/v1", api_key="sk-tk-...")

res = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Explain RAG in two sentences."},
    ],
)
print(res.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://taikhoangiare.vn/v1", apiKey: process.env.TKGR_KEY });

const res = await client.chat.completions.create({
  model: "claude-sonnet-5",
  messages: [{ role: "user", content: "Explain RAG in two sentences." }],
});
console.log(res.choices[0].message.content);

curl https://taikhoangiare.vn/v1/chat/completions \
  -H "Authorization: Bearer $TKGR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Explain RAG in two sentences."}]
  }'

Charged after the response by input and output tokens at the model's price. Empty or failed responses are free.

Streaming

Set "stream": true to receive Server-Sent Events. Token usage is included in the final chunk.

stream = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[{"role": "user", "content": "Write a haiku about APIs."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)

Anthropic Messages

Use the official Anthropic SDK with base_url="https://taikhoangiare.vn" (the SDK appends /v1/messages).

import anthropic

client = anthropic.Anthropic(base_url="https://taikhoangiare.vn", api_key="sk-tk-...")

msg = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Review this function for bugs."}],
)
print(msg.content[0].text)

Responses

For clients that use the OpenAI Responses API (for example recent n8n versions).

curl https://taikhoangiare.vn/v1/responses \
  -H "Authorization: Bearer $TKGR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.8-flash", "input": "Hello"}'

Parameters

Standard OpenAI fields are accepted. Unsupported fields are ignored rather than rejected, so one request body can target several models.

Capabilities differ per model. GET /v1/chat/models reports capabilities for each one — check for tools, vision or reasoning before relying on them.

Tool calling

Describe your functions, let the model choose one, run it yourself, then send the result back in a tool message.

curl https://taikhoangiare.vn/v1/chat/completions \
  -H "Authorization: Bearer $TKGR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "What is the weather in Hanoi?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {"city": {"type": "string"}},
          "required": ["city"]
        }
      }
    }]
  }'

The model answers with choices[0].message.tool_calls. Execute the call in your own code, then continue the conversation:

messages = [
    {"role": "user", "content": "What is the weather in Hanoi?"},
    assistant_message,                       # the message containing tool_calls
    {"role": "tool", "tool_call_id": call.id, "content": '{"temp_c": 31}'},
]

Set "tool_choice": "required" to force a call, "none" to forbid one, or name a function to pin it.

Vision

Models marked vision read images passed inside the message content. Use a public URL, or a base64 data URI for local files.

{
  "model": "claude-sonnet-5",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "text", "text": "What is in this picture?"},
      {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
    ]
  }]
}

Images consume input tokens, roughly in proportion to their pixel count — resize large photos before sending them. A local file can be uploaded first with /v1/upload/media and referenced by the URL that returns.

Claude Code & Codex

One-line setup scripts configure the CLI to route through TaiKhoanGiaRe. The dashboard shows these commands with your key filled in.

# Claude Code (optional: &main=claude-opus-5)
curl -fsSL "https://taikhoangiare.vn/v1/setup-claudecode?key=sk-tk-..." | bash

# OpenAI Codex CLI (optional: &model=gpt-6-astra)
curl -fsSL "https://taikhoangiare.vn/v1/setup-codex?key=sk-tk-..." | bash

Cursor, Cline, Continue, Aider and other tools: choose “OpenAI compatible”, set the base URL to https://taikhoangiare.vn/v1 and paste your key.

Images

curl https://taikhoangiare.vn/v1/images/generations \
  -H "Authorization: Bearer $TKGR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "IMAGE_MODEL_ID", "prompt": "a lighthouse at dusk, film photo", "aspect_ratio": "16:9"}'

The response contains data[0].url when ready, or an id to poll:

curl https://taikhoangiare.vn/v1/images/jobs/JOB_ID -H "Authorization: Bearer $TKGR_KEY"

Video

curl https://taikhoangiare.vn/v1/video/generate \
  -H "Authorization: Bearer $TKGR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1-lite",
    "prompt": "slow dolly shot of a coffee cup, steam rising",
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

Video is asynchronous. Poll the job every 5–10 seconds until status is completed; the file URL is in result. Typical clips take one to five minutes.

curl https://taikhoangiare.vn/v1/video/jobs/JOB_ID -H "Authorization: Bearer $TKGR_KEY"

File upload

Upload a local image (jpg, png, webp, gif), video (mp4, mov, webm) or audio (mp3, wav, ogg) file up to 100 MB as the raw request body — not multipart. Returns a public url you can pass to any other endpoint, for example as a reference image or as the first frame of a video.

The file type is detected from the file's own bytes, not its name, so renaming an unsupported file does not get it through.

curl https://taikhoangiare.vn/v1/upload/media \
  -H "Authorization: Bearer $TKGR_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

# → {"url": "https://taikhoangiare.vn/media/AbC123.jpg", "bytes": 842113, "kind": "jpg"}

Voice

# 1. Pick a voice
curl https://taikhoangiare.vn/v1/voice-library -H "Authorization: Bearer $TKGR_KEY"

# 2. Create speech
curl https://taikhoangiare.vn/v1/text-to-speech \
  -H "Authorization: Bearer $TKGR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice_id": 9008, "text": "Welcome to TaiKhoanGiaRe."}'

# 3. Fetch the result
curl https://taikhoangiare.vn/v1/text-to-speech/JOB_ID -H "Authorization: Bearer $TKGR_KEY"

The completed result includes audio_url, audio_duration and credits_used. Priced per character of input text, so the cost is known before you send.

* Send exactly one of text or srt. The library returns a preview_url for every voice so you can listen before spending credits.

Balance & usage

Errors

Errors use the OpenAI shape: {"error": {"message": "...", "type": "..."}}.

Retries & timeouts

Retry 429, 502, 503 and 504. Never retry 400, 401 or 404 — the same request will fail again.

import time, requests

def call(body, tries=4):
    for i in range(tries):
        r = requests.post("https://taikhoangiare.vn/v1/chat/completions",
                          json=body, headers=HEADERS, timeout=120)
        if r.status_code in (429, 502, 503, 504) and i < tries - 1:
            time.sleep(2 ** i)          # 1s, 2s, 4s
            continue
        r.raise_for_status()
        return r.json()

Suggested client timeouts: 120 seconds for chat, 300 for images, and for video submit the job then poll — do not hold one connection open for minutes.

Retries are safe for your balance: a request that fails is not charged, so a repeat only pays for the attempt that actually succeeds.

Rate limits

Limits scale with usage to keep the platform fast for everyone. If you receive 429, retry with exponential backoff. Need higher limits for production? Email support@taikhoangiare.vn.

Practical guidance: keep media generation to a handful of jobs in flight at once, and spread large batches over time instead of firing hundreds of requests in one burst.

Troubleshooting

Still stuck? Email support@taikhoangiare.vn with the request time, the model ID and the error body. Every request has a record on our side.