¿Zed quiere cambiar de modelo? Conecta APIYI con endpoints compatibles con OpenAI: 2 configuraciones de Provider

Nota del autor: distingue las tres rutas de Agent de Zed, conecta APIYI a Zed con dos proveedores personalizados —OpenAI-compatible y Anthropic-compatible— y explica la Base URL, los ID de modelo, los precios y los puntos clave para solucionar problemas.

Usas el panel Agent o Inline Assistant de Zed para escribir código, quieres cambiar a otro modelo y descubres que la página de ajustes tiene varios puntos de entrada: LLM Providers, External Agents y hilos de terminal, así que no tienes claro dónde poner la clave. Y lo que pasa aún más a menudo: configuras un gateway de terceros y todo termina en un 404 o en un fallo de autenticación. Este artículo explica cómo conectar un gateway de modelos de terceros usando proveedores personalizados de Zed (OpenAI-compatible / Anthropic-compatible) y recorre todo el proceso de configuración con APIYI como ejemplo.

No es otro artículo de consulta rápida del tipo «copia y pega la configuración y listo». Primero aclara qué modelos se pueden conectar en cada una de las tres rutas de IA de Zed y después presenta dos rutas que puedes seguir al pie de la letra. El detalle que más fácilmente lleva a errores —cuándo añadir /v1 a la Base URL y cuándo no— lo explicamos por separado.

Lo esencial: al terminar, sabrás qué capa de configuración necesitas cambiar y podrás hacer que Zed Agent use modelos como claude-opus-5-5 o claude-sonnet-5-5 en 5 minutos. Y si algo sale mal, también sabrás qué comprobar primero.

---

Puntos clave para cambiar de modelo en Zed: primero distingue las tres rutas de Agent

Zed es un editor colaborativo de alto rendimiento creado por el mismo equipo original de Atom / Tree-sitter. A fecha de 2026-11-13, el repositorio de GitHub zed-industries/zed tiene aproximadamente 94,884 estrellas (según observación de la API de GitHub). La página oficial de releases indica que la versión estable del 2026-11-11 es 1.28.1, y la Preview del mismo día es 1.29.1. Se puede descargar directamente para macOS, Linux y Windows; la versión Web aún no está oficialmente disponible.

Antes de cambiar de modelo en Zed hay que tener claro algo: la documentación oficial divide las capacidades de IA en tres rutas, y cada ruta tiene una forma distinta de conectar modelos y de autenticarse. Si lo configuras en el lugar equivocado, la configuración no surtirá efecto y la clave tampoco será leída por otra ruta.

Ruta	¿De dónde viene el modelo?	¿Quién gestiona la autenticación?	Uso típico
Zed Agent	LLM Providers (alojados por Zed, clave del proveedor, suscripción, gateway, modelo local)	Zed mismo; la clave se guarda en el llavero del sistema	Panel Agent, Inline Assistant, herramientas integradas / profiles / skills / MCP
External Agents (ACP)	El agente externo elige su propio modelo	El propio agente externo lo gestiona	Ejecutar Claude Agent, Codex, OpenCode, Copilot, Cursor, etc. dentro de hilos de Zed
Terminal Threads	Lo decide la CLI / TUI que tú ejecutes	La propia configuración de la CLI	Ejecutar directamente distintas CLI de Agent en hilos de terminal

Límites de integración entre Zed Agent y External Agent

«Cambiar de modelo para Zed Agent» significa configurar LLM Providers, es decir, la capa de API Access; esta es la línea principal del artículo. Los proveedores de primera clase compatibles oficialmente son Anthropic, OpenAI, Google AI, Mistral, DeepSeek, xAI y OpenCode; además se ofrecen dos tipos de endpoints personalizados: Anthropic-compatible y OpenAI-compatible. Los gateways de terceros se conectan precisamente a través de estos dos tipos de endpoints personalizados.

Si solo quieres usar Claude Agent u OpenCode en el panel, eso pertenece a External Agent y va por el Agent Client Protocol (ACP). En este caso, Zed aloja el hilo, mientras que el runtime, la autenticación y la selección del modelo normalmente corren a cargo del propio agente externo. La clave que pongas en LLM Providers no se comparte automáticamente con él; Claude Agent necesita ejecutar /login en su propio hilo. Los agentes externos se pueden instalar abriendo el registro con la paleta de comandos zed: acp registry. Según la documentación oficial, Zed no cobra por separado por los External Agents; la facturación queda en manos del proveedor del Agent.

---

Puntos clave de configuración del Provider personalizado en Zed

La diferencia entre los dos tipos de endpoint personalizado está principalmente en el formato de la solicitud. OpenAI-compatible usa Chat Completions, mientras que Anthropic-compatible usa la Messages API (/v1/messages). Esa diferencia determina directamente cómo se escribe la Base URL y también si se puede aprovechar la facturación de Prompt Cache.

Elemento de configuración	OpenAI-compatible	Anthropic-compatible
Formato de solicitud	/v1/chat/completions	/v1/messages
api_url de APIYI	https://api.apiyi.com/v1	https://api.apiyi.com (sin /v1)
Campo de modelo	available_models[].name + max_tokens	available_models
Interruptores de capacidad	por defecto tools=true, images=false, chat_completions=true	configurable capabilities.prompt_caching
Facturación de caché	la documentación de APIYI indica que no aplica	aplica con el formato nativo Messages
Caso de uso ideal	conectar varios modelos con un solo Provider	usar Claude como principal, contexto largo, necesidad de caché

Por qué una Base URL lleva /v1 y la otra no

Según la FAQ de Base URL de APIYI (documentación verificada el 2026-11-13), los clientes compatibles con OpenAI concatenan /chat/completions directamente después de api_url, así que api_url debe escribirse hasta el nivel /v1. En el lado de Anthropic, el cliente agrega por su cuenta /v1/messages, por lo que solo se puede poner el dominio raíz. Si se escribe https://api.apiyi.com/v1, la solicitud final terminará como /v1/v1/messages y devolverá un 404 directo.

Hay otros dos detalles a tener en cuenta. La API Key de Zed se guarda en el llavero del sistema y no se escribe en settings.json; si la variable de entorno correspondiente no está vacía, esta tendrá prioridad sobre el llavero. Además, los modelos que solo admiten la interfaz Responses deben configurar capabilities.chat_completions como false, de lo contrario Zed hará la llamada mediante Chat Completions.

Primeros pasos: conectar Zed con APIYI

Puedes elegir solo una de las dos rutas siguientes, o configurar ambas y cambiar entre ellas desde el selector de modelos. Antes de ponerte manos a la obra, prepara tu clave.

🚀 Inicio rápido: después de iniciar sesión, crea un token en la página de tokens de APIYI api.apiyi.com/token. Se recomienda crear uno específico para Zed, así puedes consultar el consumo y revocarlo en cualquier momento. La documentación de inicio rápido docs.apiyi.com/getting-started también ofrece skill.md / llms.txt, para que el Agent pueda leer las indicaciones de la plataforma.

Ruta A: conectar Zed mediante el endpoint compatible con OpenAI

1. Abre la configuración del Agent: ejecuta agent: open settings en la paleta de comandos. Según la versión, el nombre de la entrada en la interfaz puede variar un poco; guíate por el bloque LLM Providers de la página de configuración de AI / Agent.
2. En el bloque LLM Providers, haz clic en Add Provider y selecciona OpenAI-compatible como tipo.
3. Ponle al Provider el nombre que quieras, por ejemplo apiyi, que corresponde a language_models.openai_compatible.apiyi en settings.json.
4. En API URL escribe https://api.apiyi.com/v1. Aquí debes incluir /v1, que es también la forma indicada en la página de compatibilidad con OpenAI de APIYI.
5. En API Key pega el token que acabas de crear; Zed lo guardará en el llavero del sistema.
6. Añade modelos: en name pon el ID real del catálogo de modelos de APIYI, por ejemplo claude-opus-5-5, claude-sonnet-5-5, o también puedes añadir claude-fable-5-2. Rellena max_tokens según la documentación del modelo; si no estás seguro, empieza con un valor conservador y súbelo cuando todo funcione.
7. Deja los interruptores de capacidades por defecto (tools=true). Si necesitas enviar imágenes, activa images manualmente.
8. Vuelve al panel del Agent y busca apiyi o el nombre del modelo en el selector de modelos. En las versiones recientes, el selector ya admite búsqueda difusa; cuando lo hayas seleccionado, envía un mensaje para comprobar que funciona.

La ventaja de esta ruta es que un único Provider puede albergar modelos de varios proveedores. La documentación de APIYI explica que, con el endpoint compatible con OpenAI /v1/chat/completions, basta cambiar la cadena del modelo en un solo sitio para pasar de un modelo a otro.

Ruta B: Integración del endpoint compatible con Anthropic en Zed

1. Igualmente, ve a LLM Providers → Add Provider y selecciona el tipo Anthropic-compatible.
2. En API URL escribe https://api.apiyi.com, solo el dominio raíz, sin /v1. La solicitud real terminará en el endpoint nativo de Anthropic de APIYI: https://api.apiyi.com/v1/messages.
3. Pega el mismo token, o crea otro token dedicado.
4. En available_models añade IDs como claude-opus-5-5, claude-sonnet-5-5, etc.
5. Si quieres que las conversaciones de contexto largo aprovechen la caché, activa capabilities.prompt_caching. Según la página de capacidades de Claude de APIYI, la facturación de caché solo aplica con el formato nativo de Messages.
6. Selecciona ese modelo en el selector de modelos y envía un mensaje para probar.

💡 Recomendación: si tu día a día se basa principalmente en Claude, tus sesiones son largas y relees con frecuencia el mismo conjunto de archivos, la ruta B sale más rentable. Si necesitas cambiar constantemente entre varios modelos, la ruta A es más práctica. Ambas rutas pueden usar el mismo token de APIYI, cambiando de modelo según la tarea en el selector de modelos de Zed.

Referencia de precios de modelos Claude (datos al 2026-11-13)

Los siguientes datos provienen de la tabla general de modelos de APIYI, verificados en la documentación el 2026-11-13. La unidad es USD por 1M de tokens y el cobro es por uso.

ID del modelo	Entrada	Salida	Lectura de caché	Endpoints compatibles	Plataforma disponible
claude-opus-5-5	$4	$20	$0.2	chat + messages	APIYI apiyi.com
claude-opus-5-5-thinking	Igual que opus-5-5	Igual que opus-5-5	Igual que opus-5-5	Según la tabla general	APIYI apiyi.com
claude-sonnet-5-5	$2	$10	$0.1	Según la tabla general	APIYI apiyi.com
claude-fable-5-2	$8	$40	$0.2	Según la tabla general	APIYI apiyi.com

Tanto los modelos como los precios se rigen por la lista de modelos de la plataforma. Antes de configurar, puedes abrir docs.apiyi.com/models para verificar las cifras y los grupos del día (en la tabla general, claude-opus-5-5 aparece en grupos como ClaudeCode, Claude_Reverse, Claude_Enterprise, Default, SVIP).

Sobre las limitaciones de uso de claude-opus-5-5, la publicación de lanzamiento de APIYI (2026-09-23) menciona tres puntos: el modo de pensamiento no se puede establecer en disabled; si tool_choice se establece en any / tool, se devuelve un error 400; effort es medium por defecto. Si aparece un 400 cuando Zed Agent invoca herramientas, revisa primero estos puntos.

Solución de errores comunes en endpoints personalizados de Zed

Cuando falla un Provider personalizado, la mayoría de los problemas están en tres lugares: la URL, la Key y el nombre del modelo. La siguiente tabla está ordenada por frecuencia de aparición, para que puedas revisarlos uno por uno.

Síntoma	Causa común	Cómo resolverlo
404 Not Found	En Anthropic-compatible se puso /v1, y la ruta queda como /v1/v1/messages	Vuelve al dominio raíz https://api.apiyi.com
404 / ruta incorrecta	En OpenAI-compatible falta /v1	Cámbialo a https://api.apiyi.com/v1
401 / fallo de autenticación	Token incorrecto, eliminado, o una variable de entorno sobrescribió el llavero	Verifica de nuevo en api.apiyi.com/token y limpia las variables de entorno en conflicto
Modelo no existe	ID mal escrito o se usó un alias	Copia el ID original desde docs.apiyi.com/models
400 (llamada de herramientas)	tool_choice es any / tool, o se intentó desactivar el razonamiento	Ajusta según la nota dinámica de lanzamiento
Imagen no válida	En OpenAI-compatible images=false por defecto	Activa images en capabilities
Error en modelos que solo soportan Responses	Se sigue llamando como Chat Completions	Pon capabilities.chat_completions en false

🎯 Consejo de diagnóstico: si te aparece un 404, compara palabra por palabra el api_url en la configuración de Zed con el FAQ de Base URL de APIYI (docs.apiyi.com/faq/base-url-config). La mayoría de los problemas son un /v1 escrito de más o de menos.

Advertencias sobre el uso de un Provider personalizado con Zed

• Alojamiento no oficial: Los Provider personalizados OpenAI-compatible / Anthropic-compatible son una capacidad de integración genérica que ofrece Zed; un gateway de terceros no forma parte de los servicios alojados oficialmente por Zed. Si surgen problemas con el servicio, tendrás que resolverlos con el proveedor del gateway.
• La clave y la facturación son tu responsabilidad: El token y el consumo facturado están en tu propia cuenta. Se recomienda crear un token exclusivo para Zed, revisar el uso periódicamente y no poner la clave en settings.json para luego subirla al repositorio. Zed usa el llavero del sistema de forma predeterminada, lo que de por sí reduce este riesgo.
• Las condiciones de los External Agents dependen del proveedor: Las suscripciones, cuotas y condiciones de uso de Claude Agent, Codex y otros agentes externos las decide cada proveedor; son independientes de la configuración del Provider de Zed Agent.
• Diferencias entre versiones: Las descripciones de la interfaz en este artículo se basan en la documentación oficial y en la información de releases de 1.28.x / 1.29.x (fecha de observación: 2026-11-13); los nombres de las entradas pueden cambiar en versiones posteriores.

---

Preguntas frecuentes (FAQ)

Q1: ¿Qué es el endpoint compatible con OpenAI de Zed?

Es un tipo de Provider personalizado dentro de LLM Providers. Siempre que el servidor implemente la interfaz Chat Completions, puedes conectar Zed Agent mediante api_url y una lista de modelos, sin necesidad de esperar a que Zed lo adapte oficialmente.

Q2: ¿La clave que pusiste en LLM Providers sirve directamente para Claude Agent?

No. Claude Agent es un External Agent y gestiona su propia autenticación; tienes que ejecutar `/login` en su hilo. La clave de LLM Providers solo se usa para Zed Agent.

Q3: ¿Debo elegir OpenAI-compatible o Anthropic-compatible?

Si usas Claude como modelo principal y necesitas facturación con caché, elige Anthropic-compatible; si quieres conectar varios modelos con un solo Provider, elige OpenAI-compatible. Según la documentación de APIYI, la facturación con caché solo se aplica con el formato nativo de Messages.

Q4: ¿Qué ID de modelo debo poner?

Pon el ID original de la tabla general de modelos de la plataforma, por ejemplo `claude-opus-5-5`, `claude-sonnet-5-5`, `claude-fable-5-2`. Se recomienda copiarlo directamente desde docs.apiyi.com/models para evitar errores de tecleo que provoquen «modelo no encontrado».

Q5: Después de configurarlo, sigo recibiendo 404; ¿cómo lo reviso?

Primero revisa `/v1`: en OpenAI-compatible debe incluirlo, en Anthropic-compatible no debe incluirlo. Si la ruta está bien, comprueba que el ID del modelo coincida con la lista de modelos de APIYI.

Q6: ¿Dónde se guarda la clave API? ¿Se sincroniza con el repositorio?

Zed guarda la clave en el llavero del sistema, no la escribe en settings.json, así que al compartir el archivo de configuración no se incluye la clave. Ten en cuenta que, si una variable de entorno con el mismo nombre no está vacía, tiene prioridad sobre el llavero; al depurar un 401, no olvides revisar las variables de entorno.

Q7: ¿Qué limitaciones conocidas tiene esta configuración?

OpenAI-compatible no activa la capacidad de imágenes de forma predeterminada; el razonamiento de `claude-opus-5-5` no se puede desactivar, y si `tool_choice` se establece en any / tool, devuelve un 400. Además, un Provider personalizado no es un servicio alojado oficialmente por Zed; su estabilidad depende del gateway.

---

Puntos clave para integrar Zed con APIYI

• Primero define la ruta: Zed Agent usa LLM Providers; External Agent gestiona su propia autenticación.
• Dos tipos de endpoint: OpenAI-compatible usa chat; Anthropic-compatible usa messages.
• Regla de URL: para OpenAI compatible pon /v1; para Claude nativo solo el dominio raíz.
• ID del modelo: copia el ID original, como claude-opus-5-5, directamente de la tabla de modelos de APIYI.
• Caché y facturación: si necesitas caché, usa Anthropic-compatible y activa prompt_caching.
• Orden de diagnóstico: revisa en este orden: /v1, token, ID del modelo, parámetros de herramientas.
• Cómo empezar: crea un token dedicado en api.apiyi.com/token; en 5 minutos queda configurado.

---

Resumen

Para cambiar de modelo en Zed, lo clave es tener claro qué capa quieres modificar:

1. Cambiar de modelo en Zed Agent: dentro de LLM Providers, usa Add Provider para agregar un endpoint OpenAI-compatible o Anthropic-compatible.
2. External Agent: Claude Agent, OpenCode, etc., gestionan su propia autenticación; la Key no se comparte con Zed Agent.
3. Base URL: OpenAI compatible: https://api.apiyi.com/v1; Anthropic compatible: https://api.apiyi.com. Si escribes /v1 de más o de menos, obtendrás un 404.

Antes de configurar, conviene verificar los modelos y precios del día en docs.apiyi.com/models, y luego crear una Key dedicada a Zed desde la página de tokens. Primero valida con claude-sonnet-5-5 y después cambia a claude-opus-5-5 según la tarea. A través de APIYI apiyi.com puedes usar el mismo token para comparar el rendimiento bajo los dos Providers.

📚 Referencias

1. Repositorio de Zed en GitHub: observación del código fuente y del número de stars (2026-11-13)
2. Enlace: github.com/zed-industries/zed

3. Nota: la licencia principal es GPL-3.0-or-later, con componentes Apache-2.0

4. Zed AI Overview: documentación oficial de las tres vías de AI

5. Enlace: zed.dev/docs/ai/overview

6. Nota: límites de Zed Agent, External Agents y Terminal Threads

7. Zed Use API Access: configuración de Provider personalizado

8. Enlace: zed.dev/docs/ai/use-api-access

9. Nota: campos OpenAI-compatible / Anthropic-compatible y almacenamiento en el llavero (keychain)

10. Zed External Agents: Agent externo ACP

11. Enlace: zed.dev/docs/ai/external-agents

12. Nota: cómo conectar Claude Agent, Codex, OpenCode y similares

13. Zed Releases: registro de actualizaciones de versión

14. Enlace: zed.dev/releases/stable

15. Nota: contenido de la versión estable 1.28.1 y del canal Preview

16. Tabla general de modelos de APIYI: IDs de modelo y precios

17. Enlace: docs.apiyi.com/models.md

18. Nota: precios de entrada / salida / lectura de caché, según la lista vigente del día

19. FAQ de configuración de Base URL de APIYI: regla /v1

20. Enlace: docs.apiyi.com/faq/base-url-config.md

21. Nota: diferencias entre la forma de escribir la Base URL compatible con OpenAI y la nativa de Claude

22. Página de capacidades de Claude de APIYI: endpoints nativos y compatibles

23. Enlace: docs.apiyi.com/api-capabilities/claude.md

24. Nota: la facturación de caché solo aplica en formato Messages

25. Novedad del lanzamiento de claude-opus-5-5 de APIYI: límites de uso

26. Enlace: docs.apiyi.com/live/2026-09/claude-opus-5-5.md
27. Nota: descripción de los valores predeterminados de thinking, tool_choice y effort

---

Autor: equipo técnico de APIYI
Contacto técnico: si tienes problemas con la configuración, consulta el centro de documentación docs.apiyi.com o contáctanos desde la página principal de APIYI

Artículos relacionados

• Tutorial paso a paso: conecta todos los agentes con una sola clave y usa magpie, de código abierto, para unificar el acceso a la pasarela de API (con Claude Code, Codex, Pi y Hermes como ejemplos): Un tutorial práctico que puedes completar siguiendo los pasos: en unos 30 minutos, todos los agentes de programación de tu máquina (como Claude Code, Codex, Pi y Hermes) compartirán una clave API y una dirección de pasarela; incluye capturas de la interfaz de magpie, el proceso de configuración paso a paso, una comparación de las configuraciones nativas y una tabla para solucionar errores.
• Gran actualización de Antigravity al descubierto: 4 novedades y cómo conectar APIYI con Magpie: Analiza la nueva interfaz, el agente de voz, la ejecución en la nube y Gemini 4 Carbon de la gran actualización de Antigravity, indica el nivel de evidencia y presenta 3 vías y 5 pasos de configuración para integrar APIYI en Antigravity mediante Magpie.
• ¿Cómo usar una suscripción de Claude con OpenCode? Integración en 3 pasos y 5 limitaciones: OpenCode 2.2.3 añade Claude Agent: instala Claude Code y ejecuta claude auth login para usar tu suscripción en /connect; explicamos sus diferencias con el plugin retirado en marzo, 3 pasos de conexión, por qué la lectura paralela se vuelve serial y 5 límites; sin suscripción o para equipos, APIYI ofrece Claude Opus 5.5 por uso.