Documentación

Dify

Dify accede a un endpoint externo mediante un único complemento —OpenAI-API-compatible— y un único campo obligatorio, API Base URL. Complétalo y todos los nodos LLM de tus flujos de trabajo podrán usar ID de Claude y GPT con una sola clave.

Un único campo obligatorio — API Base URL, en el formulario Add Model del complemento compatible con OpenAI API — dirige todos los nodos LLM de un espacio de trabajo de Dify a Kunavo.

Proveedor de modelos → Compatible con OpenAI-API → Añadir modelo

# Integrations → Model Provider → OpenAI-API-compatible → Add Model
Type                          LLM
Model Name                    claude-sonnet-5
Model display name            Kunavo · Claude Sonnet 5
API Key                       sk-kn-...
API Base URL                  https://api.kunavo.com/v1
model name for API endpoint   (leave blank — Model Name is already the id)
Completion mode               Chat
Model context size            1000000
Upper bound for max tokens    (your own ceiling for one reply)
Function Call Type            Tool Call     # defaults to no_call
Vision Support                Support       # only if you will send images
Structured Output             Support       # defaults to not supported

# Model context size is per model, not per endpoint: 1000000 is
# claude-sonnet-5's. The table below carries the rest.

API Base URL debe incluir /v1. El complemento declara endpoint_url con la etiqueta API Base URL, lo marca como el único campo obligatorio además del nombre del modelo y le asigna el texto de ejemplo «Base URL, e.g. https://api.openai.com/v1»: ese texto es lo que resuelve la duda sobre el formulario. El propio README del complemento explica la excepción sin contradecirlo: para los tipos de modelo que no son LLM, el complemento «añade internamente la versión de la API», así que esos tipos usan el origen sin ruta para evitar duplicar /v1/v1. Ningún modelo de Kunavo pertenece a esos tipos, por lo que solo necesitas el formulario /v1.

Tres opciones están desactivadas de forma predeterminada y suelen ser la causa habitual del problema. Function Call Type tiene no_call como valor predeterminado, y Structured Output y Vision Support están configurados como no compatibles. Un modelo añadido con los valores predeterminados responde perfectamente en un nodo de chat normal y luego falla en un nodo Agent o en un flujo de trabajo que usa herramientas, lo que parece un fallo del endpoint, pero no lo es. Configúrelos al añadir el modelo, antes de depurar cualquier otra cosa.

Kunavo no ofrece modelos de embeddings, de texto a voz ni de voz a texto, y tampoco ofrece reranking; por eso, esta entrada de proveedor cubre la ranura de LLM de Dify y nada más. Una base de conocimientos indexada en modo High Quality, una URL de Rerank Endpoint o un nodo de voz conserva el proveedor que ya tenga; apuntar un nodo LLM aquí no redirige esas llamadas.

Esta configuración se ha extraído del propio listado de complementos y del esquema de proveedor de Dify en la fecha indicada abajo. Kunavo no ha ejecutado un espacio de trabajo de Dify contra su endpoint: no se ha añadido ningún modelo a un espacio de trabajo activo, no se ha ejecutado ningún flujo de trabajo ni se ha probado ningún intercambio completo de herramientas con transmisión en streaming. Una página de configuración publicada no equivale a una prueba. La curl que aparece abajo es lo que puede comprobar en diez segundos; todo lo demás depende de Dify.

¿Aún no tienes una clave? Crea una cuenta de Kunavo, genera una clave (empieza por sk-kn-) y añade crédito desde $10; las llamadas se pagan con ese saldo y las llamadas fallidas no se facturan. El panel se abre entonces en la configuración de Dify.

Paso a paso

Cree una clave en /app/keys y cópiela: se muestra una sola vez.
En Dify, abra Integrations → Model Provider, vaya a Install model providers (o al Marketplace) e instale OpenAI-API-compatible, publicado por langgenius. La documentación de Dify indica que solo el propietario del espacio de trabajo y los administradores pueden gestionar proveedores.
Haga clic en Add Model en la tarjeta de ese proveedor. El complemento no ofrece modelos predefinidos: es un proveedor customizable-model; por tanto, cada ID que quiera usar debe añadirse como entrada independiente.
Complete el formulario como se muestra arriba. Type = LLM, Model Name = el ID de Kunavo exactamente, API Key = su clave sk-kn-, API Base URL = https://api.kunavo.com/v1, Completion mode = Chat y Model context size según la tabla de abajo. Después, configure Function Call Type y, si los necesita, Structured Output y Vision Support. Guarde los cambios.
Abra un flujo de trabajo y elija el modelo en el nodo que deba usarlo. Dify asigna los modelos por nodo, no por aplicación, así que un clasificador y un redactor final pueden usar ID y precios diferentes. Las aplicaciones y los nodos que no tienen ningún modelo seleccionado recurren a Default Models → System Reasoning Model.
Ejecute un flujo de trabajo acotado y luego consulte el cargo en su cuenta de Kunavo, no en Dify; vea la nota sobre la visualización de costos más abajo.

Comprobado con Página del complemento OpenAI-API-compatible de Dify el 21 de septiembre de 2026. La configuración de terceros puede cambiar; si el nombre de un campo ya no coincide con lo que ves, esa página es la autoridad, no esta.

Esta es la versión breve. El tutorial completo —elección del modelo, coste de una sesión real y modos de fallo— está en la guía de costos de Dify.

Verifica antes de depurar el cliente

Una solicitud determina si el fallo está en el endpoint, la clave o el archivo de configuración. Si devuelve JSON, la misma URL base y la misma clave funcionan en Dify.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Qué ID de modelo introducir en el campo

Todos los modelos de texto están disponibles mediante un ID de modelo; la lista activa está en GET /v1/models, y el catálogo con precios está en la página de modelos. Las tarifas son USD por 1M de tokens, entrada / salida.

ID de modelo	Entrada / salida de Kunavo	Dónde encaja en Dify
`claude-sonnet-5`	$1.40 / $7.00	el modelo de trabajo para nodos de redacción y Agent; tamaño de contexto: 1000000
`claude-opus-5`	$3.50 / $17.50	el nodo cuya salida lee una persona, o un plan en el que equivocarse sale caro: 1000000
`claude-haiku-4-5`	$0.70 / $3.50	nodos de clasificación, enrutamiento y extracción, donde realmente se concentra el volumen de llamadas: 200000
`gpt-5-6-sol`	$2.00 / $12.00	una segunda familia con la misma clave, como entrada de modelo independiente: 1050000
`gpt-5-6-terra`	$0.70 / $4.20	nodos para documentos extensos: 1050000

La facturación es por token desde un saldo prepago, sin cuota mensual; consulta facturación. Con contexto repetido —que constituye la mayor parte de lo que envía un editor o cliente de chat—, la caché de indicaciones cambia más la factura que la elección del modelo.

Dos cosas distintas se llaman «la API de Dify»

Esta página trata sobre una de ellas, pero los resultados de búsqueda las mezclan constantemente.

Añadir un modelo a Dify: eso es lo que hace el bloque de configuración de arriba. Dify es el cliente, Kunavo es el endpoint y la credencial que pega es una clave sk-kn-. Después, todos los nodos LLM de todas las aplicaciones de ese espacio de trabajo pueden usar los ID que haya añadido.
Llamar a una aplicación de Dify desde su propio código: la Service API que Dify expone para una aplicación publicada, con su propia clave app- emitida por Dify. Esa clave pertenece a Dify, no a nosotros, y no es posible dirigirla a otro destino. Kunavo no interviene en esa dirección.

Pueden ejecutarse al mismo tiempo en la misma aplicación y, por lo general, así ocurre: su backend llama a la aplicación de Dify con una clave de Dify, y los nodos de la aplicación llaman a Kunavo con una clave de Kunavo. Son dos claves, dos facturas y dos lugares que revisar cuando algo devuelve un error 401.

Por qué Dify no muestra el costo del modelo que añadió

Los archivos de modelos predefinidos propios de Dify incluyen un bloque de precios —tarifas de entrada y salida, y una unidad por token— y Dify multiplica los recuentos de tokens por esas tarifas para mostrar una cifra en el registro. El esquema del proveedor OpenAI-API-compatible no declara ningún campo de precio, unidad ni moneda; esto se comprobó en la fecha indicada arriba. Por tanto, para un modelo añadido mediante este complemento, Dify no tiene ninguna tarifa por la que multiplicar los tokens. La columna de importes no indica que haya encontrado un descuento ni que haya introducido un error: es un campo que no existe. Consulte la cifra real en el uso de Kunavo y tome los recuentos de tokens de Dify como recuentos de tokens.

Conviene dejar activa una opción relacionada: Include Usage in Stream está habilitada de forma predeterminada y solicita al endpoint los recuentos de tokens del prompt y de la respuesta en el fragmento final del flujo. Si la desactiva, también perderá esos recuentos de tokens.

Si aloja Dify por su cuenta

La pila de Docker Compose enruta las solicitudes salientes a través de un servicio ssrf_proxy; por tanto, el endpoint debe ser accesible desde dentro de la red de contenedores, no solo desde el navegador de su portátil. Si una configuración funciona en un lugar y agota el tiempo de espera en el otro, esa suele ser la causa: es un problema de red, no de credenciales. La curl de arriba, ejecutada desde dentro del contenedor, lo comprueba directamente.

Preguntas frecuentes

¿Cómo conecto una API personalizada compatible con OpenAI a Dify?

Instale el complemento OpenAI-API-compatible, publicado por langgenius, desde Integrations → Model Provider → Install model providers o desde el Dify Marketplace. Haga clic en Add Model en su tarjeta y complete el formulario: Type, Model Name, Model display name, API Key, API Base URL, Completion mode y Model context size, además de los interruptores de capacidades. Este proveedor no incluye modelos predefinidos: es un proveedor de modelos personalizables, por lo que cada ID de modelo que quiera usar debe añadirse como entrada independiente, y cada entrada tiene su propia URL base y clave.

¿La URL base de la API de Dify debe terminar en /v1?

Sí, para un modelo de chat. El esquema de proveedor del complemento etiqueta el campo como API Base URL, lo marca como obligatorio y muestra el marcador de posición «Base URL, e.g. https://api.openai.com/v1»; por tanto, la raíz /v1 es el formato documentado. Para Kunavo, es https://api.kunavo.com/v1. El origen sin ruta solo está documentado para los tipos de modelo a los que el complemento añade la versión de API; de lo contrario, se produciría una ruta /v1/v1 duplicada. Kunavo no ofrece modelos de esos tipos, así que debe usar el formato /v1. Si falta /v1, se produce un error 404, no un error de autenticación.

¿Por qué mi nodo Agent de Dify no puede usar herramientas con el modelo que añadí?

Porque Function Call Type tiene el valor predeterminado no_call en los modelos añadidos mediante el complemento OpenAI-API-compatible, y Structured Output, Vision Support, Stream function calling y Thinking Mode Support tienen el valor predeterminado no compatible. Esas opciones reflejan lo que Dify da por cierto, no lo que comprueba; por eso, aunque el modelo admita esas capacidades, si se añade con los valores predeterminados, un nodo Agent o uno que use herramientas lo rechazará. Abra la configuración del modelo y cambie Function Call Type a Tool Call; Function Call es el formato anterior. Luego vuelva a probar antes de suponer que el problema está en el endpoint.

¿Por qué Dify no muestra el precio de un modelo añadido mediante el complemento compatible?

Porque el esquema de proveedor de ese complemento no incluye ningún campo de precios, mientras que los archivos propios de Dify para modelos predefinidos sí los incluyen. Por tanto, Dify no tiene una tarifa por token con la que multiplicar los recuentos y no muestra nada en lugar de una estimación. Consulte el importe en los registros de uso del propio proveedor y trate las cifras de Dify como recuentos de tokens. Mantener activada la opción Include Usage in Stream es lo que permite seguir recibiendo esos recuentos.

¿Añadir Kunavo a Dify equivale a exponer una aplicación de Dify como API?

No; funcionan en direcciones opuestas. Al añadir Kunavo, Dify pasa a ser el cliente: los nodos de Dify envían solicitudes a un endpoint que usted configuró con una clave de Kunavo. Con la Service API de Dify, su código es el cliente: llama a una aplicación de Dify publicada con una clave emitida por Dify, y en esa ruta no corresponde usar ninguna URL base nuestra. Una misma aplicación suele hacer ambas cosas a la vez, por lo que, si se produce un error 401, conviene identificar la clave concreta antes de revisar cualquier otra cosa.

¿Kunavo ha probado esta configuración en Dify?

No. Lo que se comprobó el 21 de septiembre de 2026 fue el material propio de Dify: el listado del complemento en el Dify Marketplace y el esquema de proveedor en el repositorio oficial de complementos de Dify, de donde provienen los nombres de los campos, su orden, los indicadores de obligatoriedad y los valores predeterminados citados aquí. Nadie ha añadido un modelo de Kunavo a un espacio de trabajo activo de Dify ni ha ejecutado un flujo de trabajo con él, así que no se afirma nada sobre la transmisión en streaming, los intercambios completos de herramientas ni los ciclos prolongados de Agent en este cliente. Lo único que puede comprobar por separado es si funcionan el endpoint y la clave; para ello sirve el comando curl de esta página.