Skip to main content

​
Cherry Studio Integration Guide for Agnes Models

​
1. Overview

This document explains how to configure Agnes custom models in Cherry Studio. After the setup is complete, Cherry Studio can call Agnes text models for conversations. Agnes image and video models can also be used through Skills or by binding them to agents.

​
2. Prerequisites

Before you start, make sure you have:
  • Cherry Studio installed.
  • An Agnes AI API Key.
  • A network environment that can access the Agnes AI API Gateway.
  • The model name you want to use.

​
3. Get an Agnes API Key

Visit the Agnes AI Platform: https://platform.agnes-ai.com/ After logging in, go to the API Key page, create an API Key, and copy it.

​
4. Add a Provider

Open Cherry Studio and go to the API provider or model settings page. Click: 
Add Provider

​
5. Select the Provider Type

For the provider type, select: 
OpenAI
Alternatively, select a custom provider type that supports OpenAI-Compatible APIs.

​
6. Enter the Provider Name

You can set the provider name as: 
Agnes
You may also use a name that is easier to identify, such as: 
Agnes AI

​
7. Enter the API Key

In the API Key field, enter the API Key obtained from the Agnes AI Platform. Example: YOUR_API_KEY In most cases, you do not need to manually add the Bearer prefix.

​
8. Enter the API Base URL

Set the API Base URL to: https://apihub.agnes-ai.com/v1 Usually, you do not need to enter the full /chat/completions endpoint. Recommended format: https://apihub.agnes-ai.com/v1 Not recommended: https://apihub.agnes-ai.com/v1/chat/completions Only use the full endpoint URL if Cherry Studio explicitly requires it.

​
9. Fetch the Model List

Click to fetch the model list. If the API Key and API Base URL are correct, Cherry Studio should be able to retrieve the available Agnes models. Select the text model: agnes-2.0-flash

​
10. Save the Configuration

After confirming that the provider name, API Key, API Base URL, and model name are correct, click Save. Once saved successfully, the Agnes model will appear in the model list.

​
11. Verify the Text Model

Create a new chat in Cherry Studio and select: agnes-2.0-flash Send a test message: 
Hello, please introduce Agnes AI.
If the configuration is correct, Cherry Studio should return a normal model response.

​
12. Using Image and Video Models

In Cherry Studio, image and video models are recommended to be used by creating Skills and binding them to agents. You can create an Agnes Image Skill to call the Agnes image model. Example Skill name: 
Agnes Image Skill
You can also create an Agnes Video Skill to call the Agnes video model. Example Skill name: 
Agnes Video Skill
After creating the Skills, bind them to an agent. You can then generate images or videos through conversations.

​
13. Troubleshooting

​
1. Unable to fetch the model list

Check whether the API Base URL is correct: https://apihub.agnes-ai.com/v1 Also confirm that the API Key is valid.

​
2. Authentication failed

Make sure the API Key is entered correctly and that the account has sufficient balance or credits.

​
3. Model not found

Confirm that the model name is correct. Recommended model: agnes-2.0-flash

​
4. Text model works, but image or video models do not

Cherry Studio’s standard OpenAI-Compatible text model configuration is usually suitable for text conversations only. For image and video models, it is recommended to use Skills or bind them as agent tools.

​
5. Request failed

Check your network, firewall, proxy, or VPN settings.