Versiones y compatibilidad

La API pública vive en /v1/*, y esa es la única versión actual. Hacemos evolucionar el contrato sin cambiar el número y registramos los cambios destacados en el changelog. La política de versiones aún se está definiendo: por ahora no hay plazos de aviso de los cambios ni una versión de ruta aparte.

Qué consideramos compatibleCopiar el enlace a la sección

Estos cambios se publican sin aviso y no cambian la versión de la ruta. Un cliente debe tolerarlos sin modificar su código:

• nuevos endpoints y nuevos parámetros opcionales de las solicitudes;
• nuevos campos en las respuestas, en los objetos output, warnings y error;
• nuevos valores de warnings[].code y nuevos code de error dentro de los estados HTTP existentes;
• nuevos modelos en el catálogo y nuevos parámetros de input en los modelos, descritos en el input_schema del modelo;
• cambios en el texto de message, que está pensado para personas.

De ahí dos reglas para una integración: ignore los campos desconocidos y base su lógica en code y status, nunca en el texto del mensaje. Los clientes que esperan un estado terminal dependen de la lista completa de valores de status, así que consideramos un valor nuevo como un cambio incompatible, igual que un nuevo type de error.

Cambios incompatiblesCopiar el enlace a la sección

Se considera incompatible eliminar o renombrar un endpoint, un campo o un parámetro, cambiar el tipo o el significado de un campo, eliminar un valor de status o un código de error, o cambiar el esquema de autenticación. Indicamos ese cambio en el changelog.

Campos obsoletosCopiar el enlace a la sección

Un campo se marca como obsoleto cuando ya no tiene significado pero se mantiene en las respuestas por compatibilidad. Eliminar un campo obsoleto es un cambio incompatible.

Versiones de los SDKCopiar el enlace a la sección

Los clientes oficiales, TypeScript clipia-ai en npm y Python clipia en PyPI, siguen semver y se publican con el mismo número: un campo, una opción o un método nuevos son una versión minor, una corrección es un patch, una eliminación o un cambio de tipo es una versión major. El historial está en los changelogs de los paquetes y en el changelog del portal. La versión del servidor MCP se lleva por separado y se ve en sus metadatos.

Estado del servicioCopiar el enlace a la sección

Hoy la API pública no tiene una página de estado independiente ni un acuerdo de nivel de servicio (SLA). Para consultas sobre interrupciones, contacte con el soporte: support@clipia.ai y Telegram @clipia_support. Si una solicitud devuelve 503 service_unavailable o 500 internal_error, repítala con una pausa creciente siguiendo la página Errores; los créditos de una generación que no llegó a iniciarse no se cobran.