Referencia de la API
Cada endpoint, con su forma de petición y respuesta. Todas las rutas son relativas a https://sketchie.ai/api.
Convenciones
Cada endpoint /v1/* requiere la cabecera Authorization: Bearer sk_.... Los errores vuelven como JSON con una bandera error y un message:
{
"error": true,
"message": "length must be a positive multiple of 30 seconds, at most 360"
}Los endpoints de generación tienen un límite de 20 peticiones por minuto. El resto comparte un límite de 200 por minuto.
Crear un explicativo
https://sketchie.ai/api/v1/explainer Inicia una generación y devuelve 202 Accepted con el registro en cola. Sondea obtener un explicativo hasta que esté ready.
{
"input": "Explain how DNS resolves a domain name",
"length": "0:30",
"aspect": "16:9",
"voice": "sketchie:sulafat",
"language": "en"
}| Campo | Tipo | Notas |
|---|---|---|
input | string | Qué explicar. Un prompt corto o el texto completo de un documento. Requerido salvo que esté presente source o sceneGraph. Alias: prompt. |
length | string or number | Duración objetivo como "M:SS" ("0:30", "1:00") o segundos. Un múltiplo positivo de 30, hasta 360. Omite para duración automática. Alias: lengthSeconds (número). |
voice | string | Opcional. Un ref de voz. Por defecto el narrador estándar (Nora). Ver Voces. |
language | string | Opcional. Un código de idioma admitido (por defecto en). Ver Idiomas. |
aspect | string | Opcional. 16:9 (por defecto), 9:16 o 1:1. |
source | string | Opcional. Un documento, artículo o transcripción para convertir en un explicativo. Cuando está presente, input pasa a ser una guía opcional. |
preset | string | Estilo de dibujo opcional: marker (por defecto), chalkboard, pencil, blueprint, crayon, clean. |
fillMode | string | Técnica de relleno de revelado opcional: A, B, C (por defecto) o D. |
sceneGraph | object | Opcional. Un scene graph pre-creado. El worker se salta la generación del grafo y lo renderiza directamente, pero este endpoint aún crea un explicativo nuevo y consume la asignación gratuita normal o la cuota del plan de pago. Para editar un explicativo existente, usa editar un explicativo. |
Devuelve el registro del explicativo: id, status, prompt, lengthSeconds, voice, language, aspect, videoUrl (null hasta que esté listo) y sceneGraph (null hasta que se genere). Vuelve un 400 por un input vacío sin source, una length malformada, o un aspect, preset, fillMode o language inválidos.
Obtener un explicativo
https://sketchie.ai/api/v1/explainer/:id Devuelve el registro completo: status actual, la videoUrl una vez ready, el sceneGraph editable, el historial de versiones (versions) y los chunks de escena de la versión principal. Un id inexistente devuelve 404.
Listar explicativos
https://sketchie.ai/api/v1/explainer?limit=50 Lista los explicativos de la clave que llama, del más nuevo al más viejo. Limitado al propietario de la clave. limit se acota de 1 a 100 (por defecto 50). Devuelve resúmenes ligeros (sin scene graph ni versiones). Usa obtener un explicativo para el registro completo.
Editar un explicativo
https://sketchie.ai/api/v1/explainer/:id/edit La cuña de editabilidad. Convierte una instrucción en lenguaje natural en un re-render dirigido. Solo se vuelven a renderizar las escenas afectadas, produciendo una nueva versión. Devuelve 202 con la versión en cola. Sondea obtener un explicativo hasta que la versión principal esté ready. Esto se añade al video existente, así que no consume otra creación de video gratis. El primer re-render de cada video es gratis. Los siguientes usan minutos del plan de pago, y a las cuentas gratis se les pide iniciar un plan. El explicativo ya debe estar ready (de lo contrario 409).
{ "instruction": "Make the title scene shorter and warmer" }Revertir a una versión
https://sketchie.ai/api/v1/explainer/:id/revert Reapunta la versión principal a una versión lista anterior y refleja su grafo y video en el registro. El objetivo debe ser una versión ready con video (de lo contrario 409).
{ "versionId": "..." }Stream de estado en vivo
https://sketchie.ai/api/v1/explainer/events Un stream de Server-Sent Events (text/event-stream). Abre una conexión y cada transición de estado de cualquiera de tus explicativos llega como un frame event: status, así puedes actualizar un estado "video listo" en el momento en que el worker termina en vez de sondear. El stream está limitado al propietario de tu clave.
Voces
https://sketchie.ai/api/v1/voices El catálogo de voces de narración. El opcional ?language=<code> filtra a voces nativas de ese idioma. Devuelve voices (cada una con un name amigable, el id a pasar como voice, language, isDefault y un preview_url reproducible) más el default global. Ver Voces.
Idiomas
https://sketchie.ai/api/v1/languages Los idiomas de narración admitidos, como { code, label, native }. Cada code es un language válido al crear. Ver Idiomas.
Estado de la cuenta
https://sketchie.ai/api/v1/account/state Devuelve videosGenerated (histórico), la image de la cuenta y isAdmin. Requiere autenticación.
Estado de facturación
https://sketchie.ai/api/v1/billing/status Requiere autenticación y devuelve 200 tanto para cuentas gratis como de pago. Una cuenta gratis devuelve plan: "free" con videoAllowance, videosUsed y videosRemaining. Una cuenta de pago también devuelve planLabel, billingInterval, trialStatus, quotaMinutes, minutesUsedThisPeriod, minutesRemaining y bonusMinutes.
Config de runtime y salud
https://sketchie.ai/api/config Público. Devuelve { "authEnforced": true }. Una comprobación de vida vive en GET /health.