External App Access (Express Models)

Call Cherry Studio Enterprise Express models via API from external apps, IDE plugins, or custom services.

Prerequisites

Before you start, make sure the following requirements are met:

An admin has created and enabled an API Key for the current user.
The target model has been enabled under Express Models.
The current user's group has permission to access the target model.
You have the enterprise API address, for example https://api.enterprise.cherry-ai.com.

Related docs:

Required Configuration

In most third-party applications that support the OpenAI protocol, you only need these 3 core settings:

Field	Value	Notes
Base URL / Server Address	Enterprise API address	Example: `https://api.enterprise.cherry-ai.com`
API Key	The user's own API key	Usually starts with `sk-`
Model	`model-id@provider_id`	Express models must include the provider suffix

Base URL tips:

If the external app automatically appends /v1/chat/completions, you can usually enter the root URL, such as https://api.enterprise.cherry-ai.com
If you use the official OpenAI SDK, set baseURL to https://api.enterprise.cherry-ai.com/v1

Model Naming Rules

When calling Express models from external applications, the model field must use the format model-id@provider_id.

Format:

model-name@x-express

Example:

qwen/qwen3-max@x-express

Important: Use the actual Model ID, not the display name shown in the UI. You must also append @x-express, otherwise the API will return Provider is required.

Common Request Examples

cURL

curl https://api.enterprise.cherry-ai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "qwen/qwen3-max@x-express",
    "messages": [
      {
        "role": "user",
        "content": "Introduce Cherry Studio Enterprise Express in three sentences."
      }
    ],
    "stream": false
  }'

Node.js (OpenAI SDK)

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.CHERRY_API_KEY,
  baseURL: 'https://api.enterprise.cherry-ai.com/v1'
})

const completion = await client.chat.completions.create({
  model: 'qwen/qwen3-max@x-express',
  messages: [{ role: 'user', content: 'Hello, please introduce yourself.' }]
})

console.log(completion.choices[0]?.message?.content)

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.enterprise.cherry-ai.com/v1",
)

resp = client.chat.completions.create(
    model="qwen/qwen3-max@x-express",
    messages=[{"role": "user", "content": "Hello, please introduce yourself."}],
)

print(resp.choices[0].message.content)

Recommended Settings in External Apps

If you are using a chat client, IDE plugin, or another third-party application, the following settings usually work:

Field	Recommended Value
Provider Type	`OpenAI Compatible` / `OpenAI`
Base URL	`https://api.enterprise.cherry-ai.com`
API Key	The user's own `sk-...` key
Model	`qwen/qwen3-max@x-express`

Compatibility note: This integration works best with applications that support manually entering a custom model name. If an app strictly depends on standard automatic model listing, you may still need to enter the model name manually.

FAQ

1. Why do I get Provider is required?

This usually means the model value does not include the provider suffix. Make sure it looks like this:

qwen/qwen3-max@x-express

2. Why do I get 401 Unauthorized or Key Expired?

Please check:

Whether the API key is correct
Whether the API key has expired
Whether the API key has been disabled by an admin

3. Why does the API say the model does not exist or I do not have access?

Please check:

Whether the target model has been enabled in the Express model list
Whether the current user's group has permission to use the model
Whether the model suffix matches the correct Express category

4. Why do I get Balance Insufficient?

This usually means the enterprise Express balance is insufficient, or the model is limited by quota settings. Ask an admin to check the balance and model status in Model Management > Express.

On this page