Documentación técnica

Referencia pública de la API

La API usa credenciales del vendedor mediante headers. Cada pedido consume créditos de la cuenta autenticada.

Base URL

Todas las llamadas públicas usan https://api.klipia.co.

Credenciales

Cada seller tiene su apiKey y apiSecret. Esas credenciales identifican la cuenta que consume créditos y no deben exponerse en frontends públicos.

Idempotencia

referenceId es el identificador de tu sistema. Si lo repetís, Klipia devuelve las solicitudes existentes para evitar duplicar generaciones por reintentos.

Créditos

Cada clip consume créditos de la cuenta autenticada. Si pedís varios idiomas, cada variante puede reservar créditos según la configuración del plan.

Endpoints

POSThttps://api.klipia.co/clips

Crea una solicitud de generación de clip.

GEThttps://api.klipia.co/clips/{id}

Consulta el estado y los datos de una solicitud.

GEThttps://api.klipia.co/clips/status

Lista solicitudes completadas o fallidas.

GEThttps://api.klipia.co/clips/{id}/video

Descarga el video final cuando la solicitud está completada.

Headers de autenticación

X-Api-Key: <apiKey del seller>
X-Api-Secret: <apiSecret del seller>
Content-Type: application/json

Ejemplo de request

{
  "referenceId": "IMG-84591-LATAM",
  "language": ["ESP", "BRA"],
  "productTitle": "Bicicleta electrica M1 Max",
  "imageUrl": [
    "https://seller.com/images/m1max-frente.jpg",
    "https://seller.com/images/m1max-detalle.jpg"
  ],
  "PresenterID": "presenter_123",
  "durationSeconds": 10,
  "callbackUrl": "https://seller.com/webhooks/klipia"
}

Ejemplo con curl

Este ejemplo crea una solicitud usando imágenes públicas. Para pruebas con imagen embebida, reemplazá imageUrl por imageBase64.

curl -X POST "https://api.klipia.co/clips" \
  -H "X-Api-Key: <apiKey del seller>" \
  -H "X-Api-Secret: <apiSecret del seller>" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "IMG-84591-LATAM",
    "language": ["ESP", "BRA"],
    "productTitle": "Bicicleta electrica M1 Max",
    "imageUrl": [
      "https://seller.com/images/m1max-frente.jpg",
      "https://seller.com/images/m1max-detalle.jpg"
    ],
    "PresenterID": "presenter_123",
    "durationSeconds": 10,
    "callbackUrl": "https://seller.com/webhooks/klipia"
  }'

Campos principales del request

Field	Type	Required	Description
referenceId	string	Sí	Identificador de producto o solicitud en tu propio sistema. Si lo repetís, devuelve las solicitudes existentes.
imageUrl	array<string>	Condicional	Array de URLs públicas de imágenes del producto. Obligatorio si no se envía imageBase64.
imageBase64	string	Condicional	Imagen del producto en Base64, hasta 20 MB. Obligatorio si no se envía imageUrl.
language	array<string>	No	Idiomas solicitados. ESP es el valor por defecto. BRA/PT se aceptan para portugués. Máximo 5.
productTitle	string	No	Nombre que describe el producto de las imágenes. Si se omite, Klipia usa referenceId.
PresenterID	string	No	Es el ID del presentador como se puede ver desde la plataforma.
callbackUrl	string	No	URL de webhook para cambios de estado.
durationSeconds	number	No	Duración del clip entre 10 y 60 segundos, en múltiplos de 10. El valor por defecto es 10.

Ciclo de vida de la solicitud

Estado	Significado	Próximo paso
queued	La solicitud fue aceptada y quedó en cola.	Guardá el identificador de la solicitud y consultá estado o esperá callback.
processing	Klipia está generando el clip.	Mostrá estado en progreso y evitá crear otra solicitud con el mismo referenceId.
completed	El clip está listo.	Usá videoUrl o GET /clips/{id}/video para descargarlo.
failed	No se pudo completar la generación.	Revisá el error devuelto y permití reintento si corresponde.

Requisitos de imagen

Enviá imageUrl o imageBase64. Al menos uno de los dos es obligatorio.
Cada URL dentro de imageUrl debe ser accesible públicamente por los servidores de Klipia.
imageBase64 permite enviar la imagen dentro del request, con un límite de 20 MB.
Usá imágenes claras del producto, con buena resolución y sin marcas de agua innecesarias.

Buenas prácticas de integración

Para grandes volúmenes, usá referenceId estable por producto o publicación para que los reintentos sean seguros.
Si tu sistema soporta webhooks, enviá callbackUrl y procesá cambios de estado sin hacer polling constante.
Si preferís consultar resultados por lotes, usá /clips/status con el parámetro status para listar solicitudes completadas o fallidas.
Guardá identificador de solicitud, referenceId, language, status y videoUrl en tu sistema para poder auditar cada generación.

Campos opcionales avanzados

backgroundeffectsspeechmusicpromptcallToActionadditionalTextmentionBrandEnabledmentionBrandTextvoiceEnabledvoiceStyleTextsubtitlesEnabledsubtitleStylesubtitleXsubtitleY

Errores comunes

Código	Causa probable	Acción recomendada
AUTHENTICATION_FAILED	apiKey o apiSecret inválidos.	Verificá headers y que la API esté habilitada para la cuenta.
REFERENCE_ID_REQUIRED	No se envió referenceId.	Enviá un identificador único de tu sistema.
IMAGE_REQUIRED	No se envió imageUrl ni imageBase64.	Incluí una URL pública o la imagen en Base64.
AVATAR_NOT_AVAILABLE	El presentador indicado no está disponible para el seller.	Usá un PresenterID habilitado o dejá PresenterID vacío.
INSUFFICIENT_CREDITS	La cuenta no tiene créditos suficientes.	Recargá créditos o reducí la cantidad de variantes solicitadas.
CLIP_NOT_FOUND	El identificador de la solicitud no existe o no pertenece a esas credenciales.	Validá el identificador de la solicitud y las credenciales del seller.
CLIP_NOT_READY	El video todavía no está completado.	Esperá status completed antes de descargar.

Respuestas y estados

{
  "id": "clp_01HZYT8F4B8K3Z7M2K",
  "referenceId": "IMG-84591-LATAM",
  "status": "queued",
  "creditsReserved": 2,
  "estimatedSeconds": 120
}

{
  "id": "clp_01HZYT8F4B8K3Z7M2K",
  "referenceId": "IMG-84591-LATAM",
  "status": "completed",
  "videoUrl": "https://api.klipia.co/clips/clp_01HZYT8F4B8K3Z7M2K/video",
  "language": "ESP"
}

queuedprocessingcompletedfailed

Callback webhook

Si enviás callbackUrl, Klipia notifica cambios relevantes de la solicitud. Tu endpoint debe aceptar POST con JSON.

{
  "id": "clp_01HZYT8F4B8K3Z7M2K",
  "referenceId": "IMG-84591-LATAM",
  "status": "completed",
  "language": "ESP",
  "videoUrl": "https://api.klipia.co/clips/clp_01HZYT8F4B8K3Z7M2K/video",
  "updatedAt": "2026-08-17T18:45:00Z"
}

Consulta de estado

Para integraciones de alto volumen, /clips/status permite listar solicitudes completadas o fallidas. Recibe el parámetro status, por ejemplo completed.

GET /clips/status?status=completed

{
  "items": [
    {
      "id": "clp_01HZYT8F4B8K3Z7M2K",
      "referenceId": "IMG-84591-LATAM",
      "status": "completed",
      "updatedAt": "2026-08-17T18:45:00Z"
    }
  ]
}