APIMaster.ai
Documentación APIMaster.ai
Quick startAPIMaster.aiMarketplace

Configuración de clave API de OpenCode AI — Config compatible con OpenAI

Cómo configurar OpenCode AI con una clave API personalizada de APIMaster.ai. Añade APIMaster como proveedor compatible con OpenAI en opencode.jsonc y accede a Claude, GPT-5.5 y DeepSeek con entrada de imágenes (Vision) y niveles opcionales de Reasoning.

OpenCode Desktop es el cliente gráfico para OpenCode (actualmente en beta): sesiones de agente local, edición de archivos y ejecución de shell. APIMaster.ai es compatible con OpenAI — agrégalo en Settings → Providers → Custom provider.

Obtén tu API Key primero. Usa el placeholder your_apimaster_key a continuación; las capturas de pantalla ocultan las claves reales.

Prerrequisitos

  1. OpenCode Desktop instalado desde opencode.ai/download.
    • Windows: opencode-desktop-win-x64.exe
    • macOS: brew install --cask opencode-desktop o .dmg
    • Linux: .deb / .rpm / AppImage
  2. API Key de APIMaster desde la consola.

Paso 1 — Abrir Providers

  1. Inicia OpenCode Desktop y abre un workspace.
  2. Haz clic en el icono de engranaje (abajo a la izquierda).
  3. Selecciona Providers en la barra lateral.
  4. Desplázate hasta Custom provider (Añade un proveedor compatible con OpenAI mediante la URL base).
  5. Haz clic en + Connect.

Settings → Providers → Custom provider

Paso 2 — Formulario de proveedor personalizado

Campo Valor
Provider ID apimaster
Display name APIMaster.ai
Base URL https://apimaster.ai/v1
API key Tu clave de APIMaster

Formulario de proveedor personalizado

Deja Headers vacío a menos que te autentiques solo mediante headers.

Paso 3 — Añadir modelos y enviar

En la siguiente pantalla, asigna modelos (izquierda = etiqueta en OpenCode, derecha = model id enviado a APIMaster — normalmente el mismo):

Izquierda Derecha
gpt-5.4 gpt-5.4
claude-sonnet-4-6 claude-sonnet-4-6
  1. Haz clic en + Add model para más filas.
  2. Haz clic en Submit.

Añadir modelos y enviar

Elige los ids del marketplace. Evita modelos solo de generación de imágenes (ej. gpt-image-2) para el chat del agente.

¿Necesitas reconocimiento de imágenes (Vision)? gpt-5.5, claude-sonnet-4-6, claude-opus-4-7, claude-opus-4-8 y claude-haiku-4-5 admiten entrada de imágenes, pero OpenCode necesita una declaración extra de capacidad — consulta Habilitar entrada de imágenes para GPT y Claude.

Paso 4 — Elegir un modelo

  1. Inicia o abre una sesión.
  2. Abre el desplegable de modelos debajo del campo de entrada.
  3. Bajo APIMaster.ai, selecciona un modelo (ej. claude-sonnet-4-6).

Selector de modelos

Paso 5 — Probar

Envía hola o una pequeña tarea de codificación. Una respuesta normal del asistente (ediciones de archivos / shell) significa que APIMaster está conectado.

Prueba de chat

Avanzado: opencode.jsonc y Reasoning

El flujo de la interfaz de usuario anterior es suficiente para un inicio rápido. Para configurar los niveles de Reasoning / thinking effort (low, high, max, ...) para el mismo model id, edita opencode.jsonc.

Ubicación del archivo de configuración

SO Ruta
macOS / Linux ~/.config/opencode/opencode.jsonc
Windows C:\Users\<usuario>\.config\opencode\opencode.jsonc

Crea el archivo si no existe. Reinicia OpenCode Desktop o inicia una nueva sesión después de guardar.

API Key (no la pongas en el jsonc)

No almacenes tu API Key en opencode.jsonc.

Usa:

  • /connect en la terminal, o
  • Settings → Providers → Connect Provider (igual que los Pasos 1–2 anteriores).

Mantén los secretos en el almacén de autenticación de OpenCode; jsonc solo define proveedor, modelos y variantes de Reasoning.

Proveedor APIMaster en jsonc

Provider id: apimaster. Paquete npm: @ai-sdk/openai-compatible.

baseURL debe ser:

https://apimaster.ai/v1

No https://apimaster.ai/ — OpenCode añade /chat/completions. Sin /v1 obtienes https://apimaster.ai/chat/completions → 404 Not Found.

Tampoco https://api.apimaster.ai/v1 — el host con prefijo api. puede causar fallos de TLS / conexión en las pruebas. El host correcto es https://apimaster.ai/v1.

Ejemplo completo con variantes de Reasoning — descarga y sobrescribe la configuración de OpenCode:

  1. Descarga opencode.jsonc
  2. Sobrescribe (o guarda como):
    • macOS / Linux: ~/.config/opencode/opencode.jsonc
    • Windows: C:\Users\<usuario>\.config\opencode\opencode.jsonc
  3. Configura la API Key mediante /connect o la interfaz (nunca en jsonc).
  4. Reinicia OpenCode Desktop o inicia una nueva sesión.

Haz una copia de seguridad de tu archivo existente antes de sobrescribir, o fusiona solo el bloque provider.apimaster.

Estructura 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" }
          }
        }
      }
    }
  }
}

Los campos attachment y modalities en gpt-5.5 arriba habilitan la entrada de imágenes (Vision) — consulta Habilitar entrada de imágenes para GPT y Claude. Omítelos si solo necesitas chat de texto.

Principios de Reasoning

  • variants = múltiples niveles de Reasoning para un mismo model id en la interfaz.
  • Para APIs compatibles con OpenAI, OpenCode asigna reasoningEffort → reasoning_effort en el cuerpo de la solicitud.
  • Los nombres de las variantes deben coincidir con el parámetro real (high → "reasoningEffort": "high").
  • Cada modelo admite diferentes niveles — configúralos según la documentación oficial; sin reasignación oculta.

Niveles de Reasoning por modelo

Modelo Variantes de Reasoning Notas
gpt-5.4 low, medium, high, xhigh Razonamiento GPT
gpt-5.5 low, medium, high, xhigh Razonamiento GPT
deepseek-v4-flash high, max Pensamiento DeepSeek (recomendado)
deepseek-v4-pro high, max Pensamiento DeepSeek (recomendado)
claude-sonnet-4-6 low, medium, high, max Esfuerzo Claude Sonnet
claude-opus-4-7 low, medium, high, xhigh, max Esfuerzo Claude Opus
claude-opus-4-8 low, medium, high, xhigh, max Esfuerzo Claude Opus
claude-haiku-4-5 ninguno Sin niveles de esfuerzo confirmados
minimax-m3 ninguno Sin niveles de esfuerzo confirmados

Consulta opencode.jsonc para el archivo completo.

Cambiar el nivel de Reasoning en OpenCode

  1. Guarda opencode.jsonc, luego reinicia o inicia una nueva sesión.
  2. Usa el desplegable de modelo / Reasoning (ej. gpt-5.4 / high).
  3. Si es compatible con tu versión: Ctrl + Shift + D recorre los niveles de Reasoning.

Habilitar entrada de imágenes para GPT y Claude

Modelos de APIMaster.ai como gpt-5.5, claude-sonnet-4-6, claude-opus-4-7, claude-opus-4-8 y claude-haiku-4-5 admiten entrada de imágenes / Vision — leer capturas de pantalla, fotos y gráficos para reconocimiento, descripción, OCR o codificación a partir de una imagen.

Que un modelo admita imágenes ≠ que OpenCode envíe la imagen. Aunque el modelo de APIMaster.ai en sí admita visión, debes declarar la capacidad en opencode.jsonc. De lo contrario, OpenCode puede no enviar la imagen como entrada multimodal — solo pone el nombre del adjunto / archivo en el prompt, y el modelo responde algo como "el modelo actual no admite entrada de imágenes".

Los dos campos a declarar

Para cada modelo que quieras usar con imágenes, añade:

"attachment": true,
"modalities": {
  "input": ["text", "image"],
  "output": ["text"]
}
  • attachment: true le indica a OpenCode que este modelo acepta adjuntos.
  • modalities.input conteniendo "image" le indica a OpenCode que este modelo admite entrada de imágenes, por lo que OpenCode convierte la imagen en contenido multimodal image_url.

Ejemplo completo (GPT y Claude)

Descarga opencode.jsonc (los campos ya están incluidos), o fusiona el bloque provider.apimaster de abajo en tu configuración 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 habilitar la entrada de imágenes solo para gpt-5.5, añade attachment y modalities únicamente a gpt-5.5; deja los demás sin cambios.
  • Para habilitar solo Claude, añade estos campos únicamente a los modelos Claude.
  • Conserva las variantes de Reasoning existentes de cada modelo (low / medium / high / xhigh / max) — los campos de imagen y el Reasoning no entran en conflicto.
  • Tras editar opencode.jsonc, cierra y reinicia OpenCode por completo, o al menos inicia una nueva sesión, para que la configuración se recargue.
  • Nunca pongas la API Key en este archivo — configúrala mediante /connect o la interfaz (consulta Seguridad más abajo).

Origen de la imagen: prefiere subida local / base64

  • Recomendado: sube un PNG / JPG local en OpenCode. Idealmente OpenCode lo convierte en una URL de datos base64 (data:image/png;base64,...) antes de enviarlo a APIMaster — esta es la ruta verificada que funciona.
  • Pasar directamente una URL de imagen pública puede fallar. APIMaster / el upstream puede fallar al descargar una imagen pública debido a red, formato, tamaño, MIME o protección anti-hotlink, devolviendo:
    Error while downloading file. Upstream status code: 400.
    En ese caso, usa una URL de datos base64 o una subida local en lugar de depender de que el lado del modelo descargue una URL pública.

Probar que el reconocimiento de imágenes funciona

Opción A — Probar en OpenCode

  1. Cambia a apimaster/gpt-5.5 o apimaster/claude-sonnet-4-6 en el desplegable de modelos.
  2. Sube una imagen PNG / JPG.
  3. Escribe:
    Describe the main content of this image.
  • Con la configuración correcta, el modelo debería describir el contenido de la imagen.
  • Si el modelo solo menciona un nombre de archivo / adjunto, o responde "image input not supported", es probable que OpenCode no esté enviando el contenido de la imagen — verifica los campos attachment y modalities del modelo y reinicia OpenCode.

Opción B — Probar directamente vía la API

Útil para distinguir un problema del modelo de APIMaster de un problema del adaptador de OpenCode. Nunca escribas una clave real de forma fija — usa una variable de entorno.

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
  }'

Cambia model a claude-sonnet-4-6 para probar Claude de la misma manera (HTTP 200 verificado con reconocimiento de imágenes).

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.

Una respuesta 200 que describe la imagen significa que la entrada de imágenes funciona del lado de APIMaster; si OpenCode aún falla, el problema está en la configuración de attachment / modalities de OpenCode o en un reinicio pendiente.

Solución de problemas

Configuración desde la interfaz

Problema Solución
401 Verifica la clave; rótala si ha quedado expuesta
Modelo no encontrado La Base URL debe ser https://apimaster.ai/v1; el model id debe coincidir con el marketplace
No aparecen modelos de APIMaster Edita el proveedor en Settings → añade asignaciones → Submit
Lento / tiempo de espera Prueba con otro modelo; usa API Key Tester

Reasoning / jsonc

¿Por qué solo high y max para DeepSeek?
El esfuerzo de pensamiento oficial compatible con OpenAI para DeepSeek es high y max. Evita low / medium / xhigh que se reasignan de forma impredecible.

¿Por qué max para Claude Sonnet y no xhigh?
El nivel superior de Sonnet es max; xhigh es para Opus (claude-opus-4-7 / claude-opus-4-8).

¿Por qué no hay variantes para Haiku o MiniMax M3?
Sin valores documentados de reasoningEffort, omite las variantes — el modelo sigue funcionando; la interfaz simplemente no mostrará subniveles de Reasoning.

¿Sigues obteniendo error 400?

  1. baseURL = https://apimaster.ai/v1 (no la raíz del sitio).
  2. La ortografía del model id coincide con el marketplace.
  3. Clave configurada mediante /connect o la interfaz.
  4. Elimina temporalmente variants — si las solicitudes simples funcionan, el reasoning_effort elegido puede no ser compatible con ese modelo.

Entrada de imágenes / Vision

¿Por qué OpenCode dice "el modelo actual no admite entrada de imágenes"?

  • El gpt-5.5 de APIMaster.ai y varios modelos Claude sí admiten entrada de imágenes; este mensaje normalmente significa que OpenCode no está enviando la imagen como entrada multimodal.
  • Verifica que el modelo en opencode.jsonc tenga:
    "attachment": true,
"modalities": {
  "input": ["text", "image"],
  "output": ["text"]
}
  • Confirma que reiniciaste OpenCode tras editar.
  • Confirma que baseURL es https://apimaster.ai/v1.
  • Confirma que la API Key de APIMaster es válida.
  • Si una URL de imagen pública falla, usa una URL de datos base64 o una subida local.

¿Por qué el modelo solo ve el nombre del adjunto, no la imagen?

  • Normalmente OpenCode no leyó ni convirtió el adjunto en entrada de imagen — solo puso el nombre del archivo / adjunto en el prompt.
  • Habilita attachment: true y modalities.input: ["text", "image"], y usa un modelo que admita entrada de imágenes.

¿Por qué una URL de imagen pública da error?

  • APIMaster o el upstream puede estar limitado por red, formato, tamaño de archivo, MIME, protección anti-hotlink o proxy al descargar una imagen pública.
  • Ante Error while downloading file. Upstream status code: 400., cambia a una URL de datos base64.

¿Sigue sin funcionar tras añadir attachment?

  1. Cierra y reinicia por completo OpenCode.
  2. Inicia una nueva sesión para probar.
  3. Confirma que el modelo activo de la sesión es el que configuraste con campos de imagen.
  4. Confirma que la API Key es válida.
  5. Revisa los logs de OpenCode en busca de errores 401 / 400 / unsupported image / invalid content type.
  6. Usa Opción B — Probar directamente vía la API con una imagen base64 para separar un problema del modelo de APIMaster de un problema del adaptador de OpenCode.

Seguridad

  • No pongas la API Key de APIMaster en opencode.jsonc; ese archivo solo contiene proveedor, modelos, capacidades de imagen y Reasoning.
  • No pegues la clave en el chat, capturas de pantalla, issues, documentos públicos o repositorios de código.
  • Rota las claves que hayan aparecido en capturas de pantalla o registros — revócalas y regenéralas en la consola, luego actualiza el proveedor en OpenCode.
  • Prefiere el flujo /connect de OpenCode, variables de entorno o almacenamiento local de credenciales para gestionar la API Key.
  • OpenCode puede leer/escribir archivos y ejecutar comandos de shell — usa solo workspaces de confianza.

Lista de verificación

  • OpenCode Desktop instalado
  • Proveedor personalizado conectado o apimaster en opencode.jsonc
  • Base URL / baseURL = https://apimaster.ai/v1 (no https://apimaster.ai/)
  • API Key mediante /connect o interfaz (no en jsonc)
  • Al menos un modelo de chat asignado
  • (Opcional) Variantes de Reasoning coinciden con los niveles oficiales
  • El mensaje de prueba se completa correctamente

Lista de verificación de entrada de imágenes

  • baseURL es https://apimaster.ai/v1 (no https://api.apimaster.ai/v1)
  • Usando un modelo con capacidad de visión, ej. gpt-5.5 o un modelo Claude con capacidad Vision
  • El modelo tiene attachment: true
  • El modalities.input del modelo contiene "image"
  • OpenCode reiniciado tras editar opencode.jsonc
  • La API Key es válida
  • La imagen de prueba es un formato común (PNG / JPG)
  • Si una URL de imagen pública falla, se probó una URL de datos base64

Resumen

  • Claves: baseURL (https://apimaster.ai/v1), model id, API Key (/connect o interfaz), variantes de Reasoning opcionales.
  • Los nombres de variantes = valores reales de reasoning_effort.
  • Configura los niveles por modelo; omite variantes cuando no sean compatibles (Haiku, MiniMax M3).

Véase también