Model Aliases

Don’t know which model to pick? Use an alias. Kyma resolves it to our current pick for that category, so you don’t have to memorise model IDs.

Available Aliases

Alias	Resolves To	Best For
`best`	`qwen-3.6-plus`	Highest quality overall
`fast`	`gemini-3.5-flash-lite`	Lowest measured median latency
`code`	`qwen-3-coder`	Code-focused tasks
`cheap`	`deepseek-v4-flash`	Cheapest that still responds quickly
`long-context`	`gemini-3-flash`	1M token context window
`vision`	`gemma-4-31b`	Image input / multimodal
`reasoning`	`deepseek-r1`	Complex reasoning tasks
`agent`	`kimi-k2.6`	Agentic tool use workflows
`best-agent`	`kimi-k2.6`	Agentic tool use workflows (explicit alias)
`balanced`	`llama-3.3-70b`	Good quality + speed balance
`glm-flagship`	`glm-5.2`	Long-running coding agents, repo-scale engineering, 1M context
`search`	`sonar`	Live web search with citations (current events, research)

fast and cheap are chosen from our own production traffic, not from vendor claims — median latency over the last 28 days of successful, non-fallback requests. cheap is the cheapest model that still responds quickly, not the cheapest outright: the lowest price per token in the catalogue currently belongs to a model with a 75-second median, which is cheap and unusable.These are still curated picks that we re-measure periodically, not a live ranking. If you are optimising hard for one axis, compare the numbers on /models and call that model by its full ID.

Audio Aliases

Kyma also exposes shortcuts for the audio stack. Use them with /v1/audio/transcriptions or /v1/audio/understand instead of memorising provider model IDs.

Alias	Resolves To	Best For
`transcribe`	`whisper-v3-turbo`	Speech-to-text, captions, voice agents (228× realtime)
`transcribe-quality`	`gpt-4o-mini-transcribe-2025-12-15`	High-accuracy transcription, multilingual code-switching (Vi/En), conversational audio
`audio-understand`	`gemini-3-flash-audio`	Scene/tone/music recognition beyond transcription

# Transcribe with the alias
curl https://kymaapi.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $KYMA_KEY" \
  -F "file=@meeting.mp3" \
  -F "model=transcribe"

# Audio scene understanding
curl https://kymaapi.com/v1/audio/understand \
  -H "Authorization: Bearer $KYMA_KEY" \
  -F "file=@clip.mp3" \
  -F "question=What instruments and mood?" \
  -F "model=audio-understand"

For TTS (/v1/audio/speech), music (/v1/audio/music), SFX (/v1/audio/sfx), and voice ops (/v1/audio/voice-clone, /v1/audio/voice-design), pass the explicit model id (e.g. eleven-multilingual-v2, minimax-music-pro). Aliases for those will land once we settle on canonical defaults.

Usage

Use aliases anywhere you’d use a model ID:

from openai import OpenAI

client = OpenAI(base_url="https://kymaapi.com/v1", api_key="YOUR_KEY")

# Instead of remembering "qwen-3.6-plus"
response = client.chat.completions.create(
    model="best",  # → resolves to qwen-3.6-plus
    messages=[{"role": "user", "content": "Hello!"}]
)

# cURL
curl https://kymaapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -d '{"model": "code", "messages": [{"role": "user", "content": "Fix this bug"}]}'

In Coding Agents

Cline
OpenClaw
Aider
Cursor

Set Model ID to code in Cline settings.

{ "primary": "kyma/code" }

aider --model openai/best --openai-api-base https://kymaapi.com/v1

Set model to best in Cursor’s OpenAI-compatible provider settings.

Transparency

When you use an alias, Kyma adds headers so you always know which model was used:

X-Kyma-Model: qwen-3.6-plus    # actual model used
X-Kyma-Alias: best              # alias you sent

When Aliases Change

An alias is a lookup table in the API — nothing scores or re-ranks models behind it. An alias keeps pointing at the same model until we change the table, which we do when a materially better model ships. So a mapping can change between releases, but never mid-flight and never on its own. Two things follow:

Pin what you depend on. If you need a model that cannot change under you, use the full model ID (e.g. qwen-3.6-plus) instead of an alias.
Check the mapping any time with curl https://kymaapi.com/v1/models | jq '.aliases', or read X-Kyma-Model on any response to see what actually served it.

Get Current Aliases

curl https://kymaapi.com/v1/models | jq '.aliases'

{
  "best": "qwen-3.6-plus",
  "fast": "gemini-3.5-flash-lite",
  "code": "qwen-3-coder",
  "cheap": "deepseek-v4-flash",
  "long-context": "gemini-3-flash",
  "vision": "gemma-4-31b",
  "reasoning": "deepseek-r1",
  "agent": "kimi-k2.6",
  "best-agent": "kimi-k2.6",
  "balanced": "llama-3.3-70b",
  "glm-flagship": "glm-5.2",
  "search": "sonar",
  "transcribe": "whisper-v3-turbo",
  "transcribe-quality": "gpt-4o-mini-transcribe-2025-12-15",
  "audio-understand": "gemini-3-flash-audio"
}

Smart Recommendations

Not sure which alias fits? Use the recommend API:

# "I use Cline, what model should I use?"
curl "https://kymaapi.com/v1/models/recommend?agent=cline"

# "I need a coding model with tool support"
curl "https://kymaapi.com/v1/models/recommend?for=coding"

Supported agents: cline, roo-code, openclaw, claude-code, aider, opencode, cursor, kilo-code. See Models for full model details.

Guides

Use Cases

Integrations

Available Aliases

Audio Aliases

Usage

In Coding Agents

Transparency

When Aliases Change

Get Current Aliases

Smart Recommendations

​Available Aliases

​Audio Aliases

​Usage

​In Coding Agents

​Transparency

​When Aliases Change

​Get Current Aliases

​Smart Recommendations

Available Aliases

Audio Aliases

Usage

In Coding Agents

Transparency

When Aliases Change

Get Current Aliases

Smart Recommendations