APIMaster.ai
Documentação APIMaster.ai
Quick startAPIMaster.aiMarketplace

Configuração da Chave de API do OpenCode AI — Compatível com OpenAI

Como configurar o OpenCode AI com uma chave de API personalizada da APIMaster.ai. Adicione o APIMaster como provedor compatível com OpenAI no opencode.jsonc e acesse Claude, GPT-5.5 e DeepSeek com entrada de imagem (Vision) e níveis opcionais de Reasoning.

OpenCode Desktop é o cliente gráfico do OpenCode (atualmente em beta): sessões de agente local, edições de arquivos e execução de shell. APIMaster.ai é compatível com OpenAI — adicione-o em Configurações → Provedores → Provedor personalizado.

Obtenha sua Chave de API primeiro. Use o placeholder sua_chave_apimaster abaixo; as capturas de tela ocultam chaves reais.

Pré-requisitos

  1. OpenCode Desktop instalado em opencode.ai/download.
    • Windows: opencode-desktop-win-x64.exe
    • macOS: brew install --cask opencode-desktop ou .dmg
    • Linux: .deb / .rpm / AppImage
  2. Chave de API do APIMaster obtida no console.

Passo 1 — Abrir Provedores

  1. Inicie o OpenCode Desktop e abra um workspace.
  2. Clique no ícone de engrenagem (canto inferior esquerdo).
  3. Selecione Provedores na barra lateral.
  4. Role até Provedor personalizado (Adicionar um provedor compatível com OpenAI pela URL base).
  5. Clique em + Conectar.

Configurações → Provedores → Provedor personalizado

Passo 2 — Formulário do provedor personalizado

Campo Valor
ID do Provedor apimaster
Nome de exibição APIMaster.ai
URL Base https://apimaster.ai/v1
Chave de API Sua chave APIMaster

Formulário do provedor personalizado

Deixe Cabeçalhos vazio, a menos que você autentique apenas por cabeçalhos.

Passo 3 — Adicionar modelos e Enviar

Na próxima tela, mapeie os modelos (esquerda = rótulo no OpenCode, direita = id do modelo enviado ao APIMaster — geralmente o mesmo):

Esquerda Direita
gpt-5.4 gpt-5.4
claude-sonnet-4-6 claude-sonnet-4-6
  1. Clique em + Adicionar modelo para mais linhas.
  2. Clique em Enviar.

Adicionar modelos e Enviar

Escolha os ids no marketplace. Evite modelos apenas de geração de imagem (ex.: gpt-image-2) para chat de agente.

Precisa de reconhecimento de imagem (Vision)? gpt-5.5, claude-sonnet-4-6, claude-opus-4-7, claude-opus-4-8 e claude-haiku-4-5 suportam entrada de imagem, mas o OpenCode precisa de uma declaração extra de capacidade — veja Ativar entrada de imagem para GPT e Claude.

Passo 4 — Escolher um modelo

  1. Inicie ou abra uma sessão.
  2. Abra o menu suspenso de modelos abaixo da entrada.
  3. Em APIMaster.ai, selecione um modelo (ex.: claude-sonnet-4-6).

Seletor de modelo

Passo 5 — Testar

Envie olá ou uma pequena tarefa de codificação. Uma resposta normal do Assistente (edições de arquivo / shell) significa que o APIMaster está conectado.

Teste de chat

Avançado: opencode.jsonc e Raciocínio

O fluxo da interface acima é suficiente para um início rápido. Para configurar níveis de Raciocínio / esforço de pensamento (baixo, alto, máximo, …) para o mesmo id de modelo, edite o opencode.jsonc.

Localização do arquivo de configuração

SO Caminho
macOS / Linux ~/.config/opencode/opencode.jsonc
Windows C:\Users\<nome_de_usuário>\.config\opencode\opencode.jsonc

Crie o arquivo se estiver ausente. Reinicie o OpenCode Desktop ou inicie uma nova sessão após salvar.

Chave de API (não coloque no jsonc)

Não armazene sua Chave de API no opencode.jsonc.

Use:

  • /connect no terminal, ou
  • Configurações → Provedores → Conectar Provedor (mesmo que os Passos 1–2 acima).

Mantenha os segredos no armazenamento de autenticação do OpenCode; o jsonc define apenas provedor, modelos e variantes de Raciocínio.

Provedor APIMaster no jsonc

Id do provedor: apimaster. Pacote npm: @ai-sdk/openai-compatible.

baseURL deve ser:

https://apimaster.ai/v1

Não https://apimaster.ai/ — o OpenCode anexa /chat/completions. Sem /v1 você obtém https://apimaster.ai/chat/completions → 404 Não Encontrado.

Também não https://api.apimaster.ai/v1 — o host com prefixo api. pode causar falhas de TLS / conexão nos testes. O host correto é https://apimaster.ai/v1.

Exemplo completo com variantes de Raciocínio — baixe e substitua a configuração do OpenCode:

  1. Baixe opencode.jsonc
  2. Substitua (ou salve como):
    • macOS / Linux: ~/.config/opencode/opencode.jsonc
    • Windows: C:\Users\<nome_de_usuário>\.config\opencode\opencode.jsonc
  3. Configure a Chave de API via /connect ou interface (nunca no jsonc).
  4. Reinicie o OpenCode Desktop ou inicie uma nova sessão.

Faça backup do seu arquivo existente antes de substituir, ou mescle apenas o bloco provider.apimaster.

Estrutura mínima:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apimaster": {
      "name": "APIMaster.ai",
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "https://apimaster.ai/v1" },
      "models": {
        "gpt-5.5": {
          "name": "gpt-5.5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "high": { "reasoningEffort": "high" }
          }
        }
      }
    }
  }
}

Os campos attachment e modalities em gpt-5.5 acima ativam a entrada de imagem (Vision) — veja Ativar entrada de imagem para GPT e Claude. Omita-os se você só precisa de chat de texto.

Princípios do Raciocínio

  • variants = múltiplos níveis de Raciocínio para um id de modelo na interface.
  • Para APIs compatíveis com OpenAI, o OpenCode mapeia reasoningEffort → reasoning_effort no corpo da requisição.
  • Os nomes das variantes devem corresponder ao parâmetro real (high → "reasoningEffort": "high").
  • Cada modelo suporta níveis diferentes — configure de acordo com a documentação oficial; sem remapeamento oculto.

Níveis de Raciocínio por modelo

Modelo Variantes de Raciocínio Notas
gpt-5.4 low, medium, high, xhigh Raciocínio GPT
gpt-5.5 low, medium, high, xhigh Raciocínio GPT
deepseek-v4-flash high, max Pensamento DeepSeek (recomendado)
deepseek-v4-pro high, max Pensamento DeepSeek (recomendado)
claude-sonnet-4-6 low, medium, high, max Esforço Claude Sonnet
claude-opus-4-7 low, medium, high, xhigh, max Esforço Claude Opus
claude-opus-4-8 low, medium, high, xhigh, max Esforço Claude Opus
claude-haiku-4-5 nenhum Níveis de esforço não confirmados
minimax-m3 nenhum Níveis de esforço não confirmados

Veja opencode.jsonc para o arquivo completo.

Alternando Raciocínio no OpenCode

  1. Salve opencode.jsonc, depois reinicie ou nova sessão.
  2. Use o menu suspenso de modelo / Raciocínio (ex.: gpt-5.4 / high).
  3. Se suportado em sua versão: Ctrl + Shift + D alterna os níveis de Raciocínio.

Ativar entrada de imagem para GPT e Claude

Modelos da APIMaster.ai como gpt-5.5, claude-sonnet-4-6, claude-opus-4-7, claude-opus-4-8 e claude-haiku-4-5 suportam entrada de imagem / Vision — leitura de capturas de tela, fotos e gráficos para reconhecimento, descrição, OCR ou codificação a partir de uma imagem.

Um modelo suportar imagens ≠ o OpenCode enviar a imagem. Mesmo que o próprio modelo da APIMaster.ai suporte vision, você precisa declarar a capacidade no opencode.jsonc. Caso contrário, o OpenCode pode não enviar a imagem como entrada multimodal — ele apenas coloca o nome do anexo / arquivo no prompt, e o modelo responde algo como "o modelo atual não suporta entrada de imagem."

Os dois campos a declarar

Para cada modelo que você quer usar com imagens, adicione:

"attachment": true,
"modalities": {
  "input": ["text", "image"],
  "output": ["text"]
}
  • attachment: true diz ao OpenCode que este modelo aceita anexos.
  • modalities.input contendo "image" diz ao OpenCode que este modelo suporta entrada de imagem, então o OpenCode converte a imagem em conteúdo multimodal image_url.

Exemplo completo (GPT e Claude)

Baixe opencode.jsonc (campos já incluídos), ou mescle o bloco provider.apimaster abaixo na sua configuração existente:

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": [],
  "provider": {
    "apimaster": {
      "name": "APIMaster.ai",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://apimaster.ai/v1"
      },
      "models": {
        "gpt-5.5": {
          "name": "gpt-5.5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" }
          }
        },
        "claude-sonnet-4-6": {
          "name": "claude-sonnet-4-6",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-opus-4-7": {
          "name": "claude-opus-4-7",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-opus-4-8": {
          "name": "claude-opus-4-8",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "variants": {
            "low": { "reasoningEffort": "low" },
            "medium": { "reasoningEffort": "medium" },
            "high": { "reasoningEffort": "high" },
            "xhigh": { "reasoningEffort": "xhigh" },
            "max": { "reasoningEffort": "max" }
          }
        },
        "claude-haiku-4-5": {
          "name": "claude-haiku-4-5",
          "attachment": true,
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

Notas:

  • Para ativar a entrada de imagem apenas para gpt-5.5, adicione attachment e modalities somente ao gpt-5.5; deixe os outros inalterados.
  • Para ativar apenas o Claude, adicione esses campos somente aos modelos Claude.
  • Mantenha as variantes de Raciocínio existentes de cada modelo (low / medium / high / xhigh / max) — os campos de imagem e o Raciocínio não entram em conflito.
  • Após editar o opencode.jsonc, encerre completamente e reinicie o OpenCode, ou pelo menos inicie uma nova sessão, para que a configuração seja recarregada.
  • Nunca coloque a Chave de API neste arquivo — configure-a via /connect ou pela interface (veja Segurança abaixo).

Origem da imagem: prefira upload local / base64

  • Recomendado: faça upload de um PNG / JPG local no OpenCode. Idealmente, o OpenCode o converte em uma URL de dados base64 (data:image/png;base64,...) antes de enviar ao APIMaster — este é o caminho verificado que funciona.
  • Passar uma URL de imagem pública diretamente pode falhar. O APIMaster / o upstream pode falhar ao baixar uma imagem pública devido a rede, formato, tamanho, MIME ou proteção contra hotlink, retornando:
    Error while downloading file. Upstream status code: 400.
    Nesse caso, use uma URL de dados base64 ou upload local em vez de depender do lado do modelo para baixar uma URL pública.

Testar se o reconhecimento de imagem funciona

Opção A — Testar no OpenCode

  1. Mude para apimaster/gpt-5.5 ou apimaster/claude-sonnet-4-6 no menu suspenso de modelos.
  2. Faça upload de uma imagem PNG / JPG.
  3. Digite:
    Describe the main content of this image.
  • Com a configuração correta, o modelo deve descrever o conteúdo da imagem.
  • Se o modelo mencionar apenas um nome de arquivo / anexo, ou responder "image input not supported," o OpenCode provavelmente não está enviando o conteúdo da imagem — verifique os campos attachment e modalities do modelo e reinicie o OpenCode.

Opção B — Testar diretamente pela API

Útil para distinguir um problema do modelo APIMaster de um problema do adaptador OpenCode. Nunca fixe uma chave real no código — use uma variável de ambiente.

Linux / macOS:

export APIMASTER_API_KEY="your APIMaster API key"

curl https://apimaster.ai/v1/chat/completions \
  -H "Authorization: Bearer $APIMASTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Describe this image." },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,YOUR_IMAGE_BASE64"
            }
          }
        ]
      }
    ],
    "max_tokens": 1000
  }'

Troque model para claude-sonnet-4-6 para testar o Claude da mesma forma (HTTP 200 verificado com reconhecimento de imagem).

Windows PowerShell:

$env:APIMASTER_API_KEY = "your APIMaster API key"
# Convert a local image to base64, put it into image_url.url as data:image/png;base64,...
# Then call https://apimaster.ai/v1/chat/completions with the same JSON body.

Uma resposta 200 que descreve a imagem significa que a entrada de imagem funciona no lado do APIMaster; se o OpenCode ainda falhar, o problema está na configuração attachment / modalities do OpenCode ou em um reinício ausente.

Solução de problemas

Configuração pela interface

Problema Solução
401 Verifique a chave; rotacione se exposta
Modelo não encontrado URL Base deve ser https://apimaster.ai/v1; id do modelo deve corresponder ao marketplace
Nenhum modelo APIMaster Edite o provedor em Configurações → adicione mapeamentos → Enviar
Lento / tempo limite Tente outro modelo; use Testador de Chave de API

Raciocínio / jsonc

Por que apenas high e max para DeepSeek?
O esforço de pensamento oficial compatível com OpenAI para DeepSeek é high e max. Evite low / medium / xhigh que podem ser remapeados imprevisivelmente.

Por que max para Claude Sonnet, e não xhigh?
O nível máximo do Sonnet é max; xhigh é para Opus (claude-opus-4-7 / claude-opus-4-8).

Por que nenhuma variante para Haiku ou MiniMax M3?
Sem valores documentados de reasoningEffort, pule as variantes — o modelo ainda funciona; a interface apenas não mostrará subníveis de Raciocínio.

Ainda recebendo erro 400?

  1. baseURL = https://apimaster.ai/v1 (não a raiz do site).
  2. A grafia do id do modelo corresponde ao marketplace.
  3. Chave configurada via /connect ou interface.
  4. Remova variants temporariamente — se as requisições simples funcionarem, o reasoning_effort escolhido pode não ser suportado para aquele modelo.

Entrada de imagem / Vision

Por que o OpenCode diz "the current model does not support image input"?

  • O gpt-5.5 e vários modelos Claude da APIMaster.ai suportam entrada de imagem; essa mensagem geralmente significa que o OpenCode não está enviando a imagem como entrada multimodal.
  • Verifique se o modelo no opencode.jsonc tem:
    "attachment": true,
"modalities": {
  "input": ["text", "image"],
  "output": ["text"]
}
  • Confirme que você reiniciou o OpenCode após a edição.
  • Confirme que o baseURL é https://apimaster.ai/v1.
  • Confirme que a Chave de API do APIMaster é válida.
  • Se uma URL de imagem pública falhar, use uma URL de dados base64 ou upload local.

Por que o modelo só vê o nome do anexo, não a imagem?

  • Geralmente o OpenCode não leu nem converteu o anexo em entrada de imagem — ele apenas colocou o nome do arquivo / anexo no prompt.
  • Ative attachment: true e modalities.input: ["text", "image"], e use um modelo que suporte entrada de imagem.

Por que uma URL de imagem pública dá erro?

  • O APIMaster ou o upstream pode ser limitado por rede, formato, tamanho do arquivo, MIME, proteção contra hotlink ou proxy ao baixar uma imagem pública.
  • Em Error while downloading file. Upstream status code: 400., mude para uma URL de dados base64.

Ainda não funciona após adicionar attachment?

  1. Encerre completamente e reinicie o OpenCode.
  2. Inicie uma nova sessão para testar.
  3. Confirme que o modelo ativo da sessão é aquele que você configurou com campos de imagem.
  4. Confirme que a Chave de API é válida.
  5. Verifique os logs do OpenCode em busca de erros de 401 / 400 / unsupported image / invalid content type.
  6. Use a Opção B — Testar diretamente pela API com uma imagem base64 para separar um problema do modelo APIMaster de um problema do adaptador OpenCode.

Segurança

  • Não coloque a Chave de API do APIMaster no opencode.jsonc; esse arquivo contém apenas provedor, modelos, capacidades de imagem e Raciocínio.
  • Não cole a chave em chat, capturas de tela, issues, documentos públicos ou repositórios de código.
  • Rotacione chaves que apareceram em capturas de tela ou logs — revogue e regenere no console, depois atualize o provedor no OpenCode.
  • Prefira o fluxo /connect do OpenCode, variáveis de ambiente ou armazenamento local de credenciais para gerenciar a Chave de API.
  • O OpenCode pode ler/escrever arquivos e executar comandos shell — use apenas workspaces confiáveis.

Lista de verificação

  • OpenCode Desktop instalado
  • Provedor personalizado conectado ou apimaster no opencode.jsonc
  • URL Base / baseURL = https://apimaster.ai/v1 (não https://apimaster.ai/)
  • Chave de API via /connect ou interface (não no jsonc)
  • Pelo menos um modelo de chat mapeado
  • (Opcional) Variantes de Raciocínio correspondem aos níveis oficiais
  • Mensagem de teste bem-sucedida

Lista de verificação de entrada de imagem

  • baseURL é https://apimaster.ai/v1 (não https://api.apimaster.ai/v1)
  • Usando um modelo com capacidade de vision, ex.: gpt-5.5 ou um modelo Claude com capacidade de Vision
  • O modelo tem attachment: true
  • O modalities.input do modelo contém "image"
  • OpenCode reiniciado após editar o opencode.jsonc
  • Chave de API é válida
  • A imagem de teste está em um formato comum (PNG / JPG)
  • Se uma URL de imagem pública falhar, tentou uma URL de dados base64

Resumo

  • Chaves: baseURL (https://apimaster.ai/v1), id do modelo, Chave de API (/connect ou interface), variantes de Raciocínio opcionais.
  • Nomes das variantes = valores reais de reasoning_effort.
  • Configure níveis por modelo; pule variantes quando não suportadas (Haiku, MiniMax M3).

Veja também