Complete API Setup Guide

What Is an API

An API (Application Programming Interface) is a "communication channel": KOA sends what you say through this channel to a large language model (such as DeepSeek, GPT, or Gemini), and the model sends back your companion's reply after processing it.

Think of it this way: KOA is their home, and the API is their brain connection. Without an API, they have no ability to think.

To set up an API, you only need three things:

• API Address — A URL provided by the service provider. In KOA, it auto-fills when you select a provider, so you usually don't need to enter it manually.
• API Key — A secret string (like sk-xxxxxxxx) that acts as your "pass". The provider uses it to identify who's making requests and charge the correct account.
• Model Name — Each provider usually offers multiple models; pick one and enter it.

Why does KOA require you to bring your own API? Because each conversation consumes computing resources from the model provider (billed per token), and you pay the provider directly. The upside: you're free to choose whichever model you like, and your conversations only pass through your own API channel — they never go through KOA's servers.

How to Choose a Model

Choosing a model comes down to three things: text quality (how natural the conversation feels), vision capability (multimodal — can it understand images), and price.

Different models also have different "personality expressiveness" — the same character card can feel slightly different with a different model. Feel free to experiment: KOA lets you switch models at any time, and your existing memories and settings won't be lost.

DeepSeek: Register & Get a Key

The best bang for your buck — a great choice for your first API.

1. Register an Account

   Go to the DeepSeek Open Platform website (deepseek.com, then navigate to "Open Platform") and sign up with your phone number.

2. Top Up

   On the "Top Up" page, add a small amount. We suggest starting with a small deposit to get a feel for usage, then topping up as needed.

3. Create an API Key

   On the "API Keys" page, click "Create API Key" to get a string starting with sk-. Copy and save it immediately — it's only shown in full this one time.

For the model name, choose deepseek-chat.

OpenAI

The official channel for the GPT series. Go to OpenAI Platform (platform.openai.com), register an account, top up, and create a key on the "API keys" page — it also starts with sk- and is only shown once.

Recommended models: gpt-4o (comprehensive capabilities) or gpt-4o-mini (cheaper). Both support vision.

Google Gemini

Made by Google, with a free tier available — perfect if you want to try it at zero cost first.

Sign in with your Google account at Google AI Studio (aistudio.google.com) and click "Get API key" to create your key. Gemini models support vision.

Other Compatible Providers

Any provider compatible with the OpenAI API format can be used with KOA — including various regional AI platforms and aggregation services. KOA also adapts to many non-official API formats.

When using such providers, you'll need three things from them: API address, Key, and model name. Then on KOA's API page, manually enter the address (select "Custom" or edit the address field directly).

Enter It in KOA

1. Select a Provider

   Open the API page in the launcher and select your provider — the API address will auto-fill. You only need to manually edit the address when using a niche provider or self-hosted proxy.

2. Enter Key & Choose Model

   Paste your API Key and enter or select the model name.

3. Set Speech Recognition Language

   While you're here, set up the speech recognition language and trigger mode (see the Voice Guide for details).

4. Apply All

   Click "Apply All" to save. This configuration takes effect globally across games, Virtual Phone, and Offline Scenes — no need to repeat the setup everywhere.

Costs & Saving Tips

Large language models charge by token (roughly equivalent to word count). KOA's token usage is modest — with DeepSeek, for example, casual gaming typically costs just a few cents per day.

• KOA has a built-in memory summarization mechanism that periodically compresses conversation history, preventing the context from growing endlessly and wasting money.
• Don't top up too much at first — start small, observe your usage patterns, then add more as needed.
• In Minecraft, if you want your companion to stop talking temporarily, use /koa quiet to pause LLM calls and save tokens during that time.

Error Reference Table

When API issues occur, the error code usually tells you exactly what went wrong:

If the cause isn't clear, check the "Logs" page in the launcher for detailed error messages — that usually pinpoints the issue. If you still can't resolve it, export a diagnostic package and reach out through the channels listed in the Help Center.