Conectar GPT e APIs de terceiros no Cherry Studio
Escolha o protocolo correto, insira o URL raiz do provedor, adicione o ID exato do modelo e verifique uma pequena solicitação antes de expandir a configuração.
Pesquisar como conectar GPT a Cherry Studio geralmente significa que você precisa de uma configuração de provedor funcional, não de um tour pelos recursos. Os campos importantes são o protocolo, a chave API, o URL base e o ID exato do modelo.
O caminho curto é:
Configurações → Serviço de modelo → escolha ou adicione um provedor → insira a credencial e o URL API → busque ou adicione um modelo → habilite o provedor → execute uma verificação de integridade.
Cherry Studio possui provedores integrados para serviços como OpenAI, Anthropic, Google Gemini, DeepSeek, Moonshot, Ollama e LM Studio. Um gateway ou serviço auto-hospedado pode ser adicionado por meio de um provedor personalizado quando expõe um endpoint OpenAI compatível, Anthropic ou Gemini. Consulte o guia oficial de configurações do provedor para obter os nomes de UI atuais.
O que você precisa antes de abrir Cherry Studio
Prepare quatro valores do serviço que você deseja usar:
| Valor | O que isso significa |
|---|---|
| Protocolo | Compatível com OpenAI, mensagens Anthropic, Gemini ou formato documentado do provedor |
| Chave API | A credencial usada para autenticar a solicitação |
| Base URL | O endereço raiz API, a menos que o provedor exija explicitamente um endpoint completo |
| Model ID | A string exata aceita pelo upstream API |
Não use uma senha de chat na web como chave API. Uma assinatura ChatGPT, uma conta API e um gateway de terceiros são caminhos de acesso separados. Use a credencial e o endpoint documentados pelo serviço selecionado.
Conecte o GPT em cinco etapas
Serviço de modelo aberto 1.
Inicie Cherry Studio e abra Configurações → Serviço de modelo. Escolha o provedor OpenAI integrado ao ligar diretamente para OpenAI. Para um gateway, agregador ou implantação privada, escolha Adicionar provedor e crie uma entrada personalizada separada.
O provedor é selecionado por seu protocolo, e não pela palavra GPT no nome do modelo. Um modelo rotulado como GPT por trás de um gateway compatível com Anthropic ainda precisa do perfil de protocolo Anthropic.
2. Preencha os campos do provedor
Use a documentação do provedor para cada campo:
| Campo Cherry Studio | O que inserir | Evite |
|---|---|---|
| Nome do provedor | Um rótulo que você reconhecerá mais tarde | Reutilizando um rótulo para endpoints não relacionados |
| Chave API | Somente o valor-chave | Espaços extras, aspas ou Bearer |
| Tipo API | O protocolo que o endpoint realmente implementa | Adivinhando pelo nome de marketing do modelo |
| Endereço API | O URL raiz documentado ou o URL completo necessário | Um URL do painel ou um caminho duplicado |
Para um serviço convencional compatível com OpenAI, Cherry Studio geralmente espera o endereço raiz e anexa a versão e o caminho da solicitação. Se um provedor mostrar https://api.example.com e https://api.example.com/v1/chat/completions, o primeiro será o URL base normal. Não adicione /v1 duas vezes. Use um caminho completo somente quando o provedor disser explicitamente para fazê-lo.
O guia do provedor personalizado cobre endpoints extras, entrada manual de modelo e serviços locais no estilo vLLM.
3. Busque ou adicione o modelo
Clique em Obter lista de modelos. Se o endpoint expor a descoberta de modelo, adicione o modelo com o botão +. O ID retornado é oficial: mantenha datas, prefixos de fornecedores, hífens e sufixos de versão exatamente como mostrados.
Se o provedor não expor uma lista de modelos, adicione o modelo manualmente. Um salvamento bem-sucedido do provedor não disponibiliza automaticamente um modelo no seletor de chat. O modelo deve ser adicionado e a troca de provedor deve ser habilitada.
4. Verifique uma solicitação curta
Use Check com o modelo que você acabou de adicionar e envie um prompt mínimo:
Reply with exactly: connection successful
Isso separa problemas de autenticação e roteamento de problemas de visão, ferramentas, contexto longo ou capacidade do agente. Confirme a chamada na página de utilização do provedor quando houver uma disponível.
5. Adicione recursos avançados, um de cada vez
Depois que o texto simples funcionar, teste streaming, imagens, ferramentas ou parâmetros de raciocínio um por um. Uma resposta de bate-papo bem-sucedida apenas prova que a rota básica de texto funciona; isso não prova que o modelo ou protocolo suporta todos os recursos que Cherry Studio expõe.
Conectando outras APIs de terceiros
Gateways compatíveis com OpenAI
Use Provedor personalizado → OpenAI quando o gateway documentar OpenAI Chat Completions ou outra superfície compatível com OpenAI. Este é o caminho usual para agregadores, gateways privados, vLLM e muitos modelos abertos hospedados.
Gateways multiprotocolo
Os gateways de estilo NewAPI podem expor bate-papo OpenAI, respostas OpenAI, mensagens Anthropic e rotas Gemini de um endereço raiz. As [instruções NewAPI] (https://docs.cherryai.com.cn/pre-basic/providers/newapi.md) de Cherry Studio explicam que o cliente seleciona o caminho da versão para o protocolo escolhido. Use a predefinição NewAPI quando o gateway seguir esse contrato; use um provedor personalizado quando ele tiver um caminho documentado ou uma variação de descoberta de modelo.
Ollama, LM Studio e vLLM
Selecione o provedor local correspondente ou use um provedor OpenAI personalizado quando o servidor local expõe um OpenAI compatível com API. Insira o nome do modelo que o servidor local realmente carregou. A execução local pode reduzir a exposição dos dados, mas os modelos locais ainda diferem em termos de visão, ferramentas, extensão do contexto e suporte ao raciocínio.
Quando a lista de modelos está vazia
Faça essas verificações em ordem:
- Confirme se o serviço implementa um ponto final de lista de modelos. Algumas APIs aceitam apenas um ID de modelo fornecido manualmente.
- Remova segmentos de caminho duplicados. Uma URL raiz que já contém
/v1pode falhar quando Cherry Studio anexa outro/v1. - Verifique se você usou o endereço API e não o endereço do painel de gerenciamento do provedor.
- Copie o ID exato do modelo retornado pelo provedor. Os nomes de exibição e os IDs API não são intercambiáveis.
- Certifique-se de que o provedor esteja ativado. Um provedor desabilitado oculta seus modelos do seletor.
Erros comuns
| Erro | Causa provável | Primeira verificação |
|---|---|---|
401 Unauthorized | Chave inválida, expirada ou formatada incorretamente | Copie novamente a chave e confirme o perfil do protocolo |
403 Forbidden | Conta, projeto, saldo ou limite de chave | Verifique as permissões e a cota do provedor |
404 Not Found | URL raiz incorreto, caminho de versão duplicado ou incompatibilidade de protocolo | Restaurar o URL base documentado |
400 Bad Request | Parâmetro ou formato de solicitação incompatível | Remova os parâmetros personalizados e tente novamente com texto simples |
model not found | ID errado ou modelo não adicionado em Cherry Studio | Copie o ID exato do modelo upstream |
| O texto funciona, mas as imagens/ferramentas falham | Modelo ou protocolo não possui essa capacidade | Verifique a lista de capacidade e rota |
| Tempo limite | Latência do provedor, problema de rede ou solicitação superdimensionada | Tente novamente com um prompt curto e um modelo |
Altere uma variável de cada vez. Comece com um provedor, um modelo e uma solicitação curta; só então adicione vários modelos ou ferramentas.
Comparando vários modelos
Cherry Studio permite alternar modelos no seletor de conversa e enviar o mesmo prompt para vários modelos selecionados. Cada seleção cria uma solicitação independente. É útil para comparação, mas não é um voto automático ou uma garantia de qualidade; a contagem de solicitações, o custo e a exposição de dados aumentam com cada modelo selecionado. O guia oficial de comparação recomenda escrever critérios de avaliação explícitos em vez de perguntar qual resposta é simplesmente “melhor”.
Use OmniaKey como um provedor
Se você não quiser manter pontos de entrada separados para GPT, Claude, Gemini e outros modelos, configure OmniaKey como um provedor personalizado compatível com OpenAI em Cherry Studio.
- Crie uma chave OmniaKey API dedicada e defina um limite de chave adequado na página Chaves API.
- Abra Configurações → Serviço de modelo → Adicionar provedor em Cherry Studio.
- Escolha o tipo compatível com OpenAI e insira o URL base e a chave no início rápido do OmniaKey.
- Obtenha a lista de modelos ou adicione um ID exato do catálogo de modelos ativos.
- Habilite o provedor, execute uma breve verificação e confirme a solicitação em Uso.
O catálogo OmniaKey atual inclui Claude, GPT, Gemini e Grok, juntamente com famílias de modelos adicionais. Os IDs e os recursos são dinâmicos, portanto, use o catálogo ativo em vez de um tutorial antigo. Uma rota compatível com OpenAI não torna todos os recursos específicos do provedor idênticos; verifique o modelo e a capacidade do protocolo antes de ativar a visão ou as ferramentas.
Perguntas frequentes
Cherry Studio pode usar qualquer API que eu encontrar?
Somente quando o serviço expõe um protocolo compatível com Cherry Studio. Um URL arbitrário sem formato de solicitação documentado, método de autenticação e ID de modelo não é suficiente.
Devo inserir um URL raiz ou /chat/completions?
Siga a documentação do fornecedor. Os provedores convencionais normalmente usam o URL raiz e permitem que Cherry Studio acrescente o caminho da solicitação; use um endpoint completo somente quando o provedor exigir explicitamente.
Por que posso conversar, mas não posso usar ferramentas ou imagens?
O sucesso do texto básico não prova que o modelo, protocolo e rota do cliente selecionados suportam ferramentas ou visão. Verifique cada capacidade separadamente.
Uma assinatura da web ChatGPT é uma chave API?
Não. Cherry Studio precisa de uma credencial de provedor API ou de uma credencial de gateway compatível. Os detalhes de login da Web nunca devem ser colados no campo-chave API.
Fontes e frescor
Este guia usaCherry Studioprovedor atual, provedor personalizado,OpenAI, NewAPI e documentação multimodelo, alémOmniaKeyatualAPIe documentação do modelo. Valores técnicos como IDs de modelo, recursos de provedor e rotas podem mudar; verificá-los no momento da configuração.