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 vendedor 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 principales

POST/clips

Crea una solicitud de generación de clip.

GET/clips/{id}

Consulta el estado y los datos de una solicitud.

GET/clips/status

Lista solicitudes completadas o fallidas.

GET/clips/{id}/video

Descarga el video final cuando la solicitud está completada.

Headers de autenticación

X-Api-Key: <sellerApiKey>
X-Api-Secret: <sellerApiSecret>
Content-Type: application/json

Ejemplo de solicitud

POST /clips
{
  "referenceId": "BIKE-1024",
  "productTitle": "Bicicleta M2 Pro",
  "imageUrl": ["https://seller.com/images/bike.jpg"],
  "PresenterID": "presenter_15",
  "durationSeconds": 10
}

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: <sellerApiKey>" \
  -H "X-Api-Secret: <sellerApiSecret>" \
  -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

Estos campos son opcionales y usan los mismos nombres conceptuales que se guardan en la cola de generación. Al crear la solicitud, Klipia normaliza estos valores y los copia a la cola como configuración de esa generación.

La UI puede mostrar algunos controles como No, Sí o Personalizado; en API eso se expresa como un campo de modo y, cuando corresponde, otro campo de texto. Para integrar, usá los valores canónicos documentados abajo.

Campo	Tipo	Cómo se usa	Ejemplo
backgroundMode	string: no \| yes \| custom	Equivale al selector Background contextual de la UI. no no agrega contexto; yes deja que Klipia lo proponga; custom usa el detalle enviado en backgroundText.	custom
backgroundText	string	Texto libre para describir el contexto visual. Se usa cuando backgroundMode es custom.	Estudio blanco, cocina moderna, calle urbana.
effectsMode	string: no \| yes \| custom	Equivale al selector Efectos contextuales de la UI. no no agrega efectos; yes deja que Klipia los proponga; custom usa effectsText.	yes
effectsText	string	Texto libre para pedir efectos o movimientos específicos cuando effectsMode es custom.	Zoom suave al producto, brillo en detalles.
speechMode	string: automatic \| product-info \| defined	Equivale al selector Speech para audio. automatic deja que Klipia escriba lo que dice el presentador; product-info usa speechText como datos del producto; defined usa speechText como speech completo.	automatic
speechText	string	Texto usado según speechMode. Puede ser el guion exacto o información que Klipia debe considerar al hablar del producto.	Destacar batería, comodidad y uso diario.
musicMode	string: no \| ai	Equivale al selector Música de fondo. no no pide música; ai pide música automática coherente con el clip.	ai
musicText	string	Orientación descriptiva para la música. Hoy la UI no muestra texto para música, pero la API lo puede recibir como referencia.	Música moderna y energética, volumen bajo.
promptMode	string: automatic \| guide \| defined	Equivale al selector Guión para video. automatic deja que Klipia arme el guion visual; guide usa customPromptText como pautas; defined usa customPromptText como guion completo.	guide
customPromptText	string	Texto usado por promptMode. Puede ser una pauta general o el guion completo del video.	Crear un video comercial breve, directo y orientado a conversión.
mentionBrandEnabled	boolean	Equivale al selector Mencionar la Marca. true pide que el presentador mencione la marca; false evita esa indicación.	true
mentionBrandText	string	Nombre de marca o texto exacto a mencionar cuando mentionBrandEnabled está activo.	Klipia Store
voiceEnabled	boolean	Equivale al selector Estilo de voz. true permite orientar acento, tono o ritmo con voiceStyleText. El presentador del clip habla siempre.	true
voiceStyleText	string	Describe el tono de voz y estilo de locución.	Cercano, comercial, entusiasta, español rioplatense.
subtitlesEnabled	boolean	Equivale al selector Subtítulos. true incluye subtítulos; false no los agrega.	true
subtitleStyle	string	Estilo visual de subtítulos. Valores: bold-white-shadow, yellow-black, white-purple-box, black-cream-box u orange-white.	bold-white-shadow
subtitleX	number	Posición horizontal de los subtítulos expresada como porcentaje del ancho del video.	50
subtitleY	number	Posición vertical de los subtítulos expresada como porcentaje del alto del video.	82
callToActionMode	string: none \| comprar \| mis-productos \| favoritos \| compartir \| mix	Equivale al selector Llamada a la Acción. Define qué cierre comercial se agrega al clip.	comprar

Ejemplo de configuración avanzada

{
  "durationSeconds": 20,
  "backgroundMode": "custom",
  "backgroundText": "Estudio blanco, luz suave, estilo premium",
  "effectsMode": "yes",
  "speechMode": "product-info",
  "speechText": "Destacar autonomia, comodidad y uso diario.",
  "musicMode": "ai",
  "promptMode": "guide",
  "customPromptText": "Mostrar el producto de forma clara y comercial.",
  "mentionBrandEnabled": true,
  "mentionBrandText": "Klipia Store",
  "voiceEnabled": true,
  "voiceStyleText": "Tono cercano, comercial y ritmo dinamico.",
  "subtitlesEnabled": true,
  "subtitleStyle": "bold-white-shadow",
  "subtitleX": 50,
  "subtitleY": 82,
  "callToActionMode": "comprar"
}

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 vendedor.	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 vendedor.
CLIP_NOT_READY	El video todavía no está completado.	Esperá status completed antes de descargar.

Respuestas y estados

{
  "id": "clip_82371",
  "status": "processing"
}

{
  "id": "clip_82371",
  "referenceId": "BIKE-1024",
  "status": "completed",
  "videoUrl": "https://api.klipia.co/clips/clip_82371/video"
}

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"
    }
  ]
}