---
title: Versiones y compatibilidad
description: "La API de Clipia evoluciona en una sola versión, /v1: qué cambios se consideran compatibles, qué va al changelog, campos obsoletos y versiones de los SDK."
icon: GitBranch
---

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](/es/docs/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 compatible

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 incompatibles

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](/es/docs/changelog).

## Campos obsoletos [#deprecated]

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.

| Campo | Dónde | Ahora | Qué usar en su lugar |
|-------|-------|-------|----------------------|
| `queue_position` | respuestas de [envío](/es/docs/api-reference/submit) y [estado](/es/docs/api-reference/status) | siempre `0`: la posición en la cola no se calcula | `status` y `progress` |

## Versiones de los SDK

Los clientes oficiales, TypeScript [`clipia-ai`](/es/docs/sdk/typescript) en npm y Python [`clipia`](/es/docs/sdk/python) 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](/es/docs/changelog). La versión del servidor MCP se lleva por separado y se ve en sus metadatos.

## Estado del servicio [#status]

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](https://t.me/clipia_support). Si una solicitud devuelve `503 service_unavailable` o `500 internal_error`, repítala con una pausa creciente siguiendo la página [Errores](/es/docs/api-reference/errors); los créditos de una generación que no llegó a iniciarse no se cobran.