Automatizar videos con letras

Usa @youka/sdk y @youka/cli versión 0.2.0 o posterior para estos ejemplos. Los proyectos creados a través de la API permanecen disponibles en tu biblioteca de Youka.

Elegir un flujo de trabajo y un modelo

kind selecciona el flujo de trabajo del proyecto. karaoke separa stems. lyric-video usa el audio original y no cobra por la separación. Si se omite kind, se conserva el comportamiento existente de karaoke. El procesamiento de letras es una elección independiente entre alineación, transcripción o sin procesamiento. Descubre los modelos y la elegibilidad de la cuenta antes de elegir un modelo.

youka capabilities --json

const capabilities = await client.capabilities.get();
const eligibleModels = capabilities.models.filter(
  (model) => model.eligible && model.workflows.includes("lyric-video"),
);

La respuesta describe los ID de modelo, operaciones, entradas de audio, semántica del texto proporcionado, flujos de trabajo, compatibilidad de idiomas y funciones requeridas. suppliedTextHandling distingue la alineación, los términos clave del proveedor y la corrección después de la transcripción. La elegibilidad refleja la cuenta autenticada. El descubrimiento describe la compatibilidad configurada, no una garantía de disponibilidad del proveedor. La validación de la solicitud y las cotizaciones de precio siguen siendo la referencia. Los modelos que requieren voces aisladas no pueden procesar un lyric video sin separación. Úsalos en un flujo de trabajo de karaoke con un modelo de separación que produzca voces. Wav2Vec2 es un modelo de alineación. ElevenLabs Scribe es un modelo de transcripción. El texto de transcripción proporcionado es una guía, no una garantía de una salida de texto idéntica.

Crear y cotizar proyectos

import { AlignmentModel, YoukaClient } from "@youka/sdk";

const client = new YoukaClient({ apiKey: process.env.YOUKA_API_KEY! });
const operation = await client.projects.create(
  {
    kind: "lyric-video",
    source: { type: "path", path: "./song.wav" },
    title: "Example song",
    lyricsSource: {
      type: "transcribe",
      syncModel: AlignmentModel.ElevenLabsTranscription,
      lyrics: "Optional reference lyrics",
    },
  },
  { idempotencyKey: "example-song-create-v1" },
);
const { project } = await client.projects.wait(operation);

Alinea letras proporcionadas con un modelo anunciado para lyric videos.

youka project create ./song.wav --kind lyric-video --mode align \
  --sync-model audioshake-alignment --lyrics 'Line one
Line two' --json

Mantén la separación para proyectos de karaoke. Omite --kind o pasa --kind karaoke y elige --split-model. Usa --mode none para crear sin procesamiento de letras. Las solicitudes de lyric-video rechazan opciones de separación. Cotiza la misma fuente, flujo de trabajo y opciones de procesamiento antes de la creación.

youka project quote ./song.wav --kind lyric-video --mode transcribe \
  --sync-model elevenlabs-transcription --json

Una cotización comprueba la misma compatibilidad de modelos, política de idioma, funciones de la cuenta, duración y reglas de almacenamiento que la creación. Su desglose de créditos tiene cero créditos de separación para lyric videos. Una cotización no reserva capacidad ni créditos; el estado de la cuenta puede cambiar antes de la creación.

Corregir tiempos sin trabajos de procesamiento

Lee alineaciones mediante GET /projects/{projectId}/alignments, y luego obtén el recurso elegido mediante GET /projects/{projectId}/alignments/{alignmentId}. La lista contiene alignments, selectedAlignmentId y selectionRevision. Cada recurso incluye la carga útil de tiempos, revision, selected y selectionRevision. Las actualizaciones reemplazan el objeto alignment completo. No ejecutan sincronización ni crean una retención de créditos de procesamiento. Conserva los ID, el texto, los índices de línea/palabra/subpalabra, la información del cantante y las traducciones al editar. Los tiempos son segundos decimales absolutos. Aplica cualquier corrección deseada una sola vez en los valores enviados. No añadas la misma corrección de nuevo como un offset de exportación.

const snapshot = await client.projects.alignments.list(project.id);
const current = snapshot.alignments.find(
  (alignment) => alignment.id === snapshot.selectedAlignmentId,
);
if (!current) throw new Error("Project has no alignment to edit");

const corrected = structuredClone(current.alignment);
corrected.items[0]!.start = 0.75;
corrected.items[0]!.end = 1.25;

const saved = await client.projects.alignments.update(project.id, current.id, {
  alignment: corrected,
  expectedRevision: current.revision,
  select: true,
  expectedSelectionRevision: snapshot.selectionRevision,
});

Usa select: true para guardar y seleccionar de forma atómica. Para seleccionar tiempos existentes sin reemplazarlos, llama a client.projects.alignments.select(projectId, alignmentId, { expectedRevision, expectedSelectionRevision }). La revisión de la alineación protege el contenido de los tiempos. La revisión de selección protege qué alineación está activa. Un token desactualizado produce HTTP 409. Obtén el recurso más reciente, compara las ediciones y envía un reemplazo deliberado. No actualices automáticamente el token y sobrescribas los cambios de otro editor. El CLI acepta un archivo JSON o la entrada estándar. Un archivo de importación contiene { "alignment": { "items": [...] }, "expectedRevision": "..." }. Incluye select y expectedSelectionRevision al seleccionar de forma atómica. Los recursos exportados también contienen metadatos de respuesta, así que extrae los campos de solicitud antes de importar.

youka project timings list proj_example --json
youka project timings get proj_example aln_example --json > timing-resource.json
youka project timings import proj_example aln_example --body corrected-request.json --json
youka project timings select proj_example aln_example \
  --expected-revision "$ALIGNMENT_REVISION" \
  --expected-selection-revision "$SELECTION_REVISION" --json

Las importaciones aceptan hasta 100.000 elementos. Cada tiempo de finalización debe ser estrictamente mayor que su inicio. Se rechazan números inválidos, tiempos negativos, índices inválidos, rangos de longitud cero o invertidos, y tiempos que superen una duración conocida del proyecto. Se mantienen compatibles las superposiciones legítimas y la temporización de dúos. Reabre o actualiza un proyecto de app ya abierto después de una edición externa.

Exportar una versión elegida

youka project versions proj_example --json
youka export create proj_example --version-id ver_example --local \
  --transparent --mute-all --fps 30 --output ./overlay.mov --json

versionId es opcional en las solicitudes de exportación y en las actualizaciones de configuración, y en la query del GET de configuración. Omitirlo conserva el comportamiento de versión primaria. La alineación seleccionada pertenece al proyecto, mientras que el estilo y la configuración pertenecen a la versión elegida.

const versions = await client.projects.versions.list(project.id);
const versionId = versions[0]!.id;
const stemVolumes = Object.fromEntries(
  project.stems.map((stem) => [stem.id, 0]),
);
const payload = await client.exports.prepareLocal(project.id, {
  versionId,
  transparent: true,
  stemVolumes,
  fps: 30,
});
console.log(payload.versionId, payload.alignmentId, payload.alignmentRevision);

await client.exports.create(project.id, {
  target: "local",
  versionId,
  transparent: true,
  stemVolumes,
  fps: 30,
  outputPath: "./overlay.mov",
});

Los handles de operaciones de exportación en la nube y las cargas útiles locales incluyen versionId, alignmentId y alignmentRevision. Estos campos identifican la instantánea de tiempos usada para esa exportación o carga útil preparada. Cada preparación lee el estado actual, así que una exportación posterior separada puede observar ediciones más recientes. Guarda la carga útil devuelta cuando un renderizador externo deba renderizar exactamente esa instantánea preparada, y actualízala cuando caduquen las URL de medios firmadas. La salida local transparente usa ProRes 4444 en un contenedor MOV. --mute-all asigna todos los stems del proyecto a volumen cero. El silencio y la ausencia de una pista de audio son propiedades de salida distintas; inspecciona el archivo renderizado si una herramienta posterior requiere una de ellas. El renderizado local no consume créditos de exportación en la nube y sigue sujeto a la elegibilidad de funciones existente. La temporización de palabras, los offsets globales de audio y la anticipación de letras son configuraciones independientes. Los diseños existentes controlan la visibilidad de las líneas. Esta versión no promete un intervalo de revelado fijo para cada línea ni añade una API separada de adjuntos para backing-track.

Operar un catálogo de forma segura

Mantén un manifiesto con un ID de elemento estable, huella de la fuente, configuración de la operación, clave de idempotencia, ID de proyecto/tarea y el último resultado terminal. Reutiliza una clave solo para reintentos de la misma solicitud. Persiste los resultados de creación antes de esperar la finalización para que un reinicio pueda reanudar el sondeo. Las subidas y la preparación de archivos locales tienen su propio ciclo de vida; una clave de idempotencia de creación no deduplica todas las subidas. El ejecutable ejemplo de catálogo acepta ID de archivos de entrada precargados y persiste un checkpoint por elemento. Un manifiesto se ve así.

[
  {
    "id": "song-001",
    "request": {
      "kind": "lyric-video",
      "inputFileId": "owned-upload-id",
      "title": "Example song",
      "lyricsSource": {
        "type": "transcribe",
        "syncModel": "elevenlabs-transcription"
      }
    }
  }
]

Descarga el ejemplo como catalogue.ts. Instala sus dependencias y configura YOUKA_API_KEY. Usa un proyecto de Node.js con "type": "module" en su package.json.

npm install @youka/sdk@^0.2.0 tsx
npx tsx ./catalogue.ts ./manifest.json ./catalogue-state 1

Vuelve a ejecutarlo con el mismo manifiesto y directorio de estado para reanudar el sondeo de trabajos aceptados o reintentar un envío incierto con su clave original. Los trabajos completados y fallidos se registran y se omiten. Las solicitudes cambiadas requieren nuevos ID de elemento. El bloqueo del directorio impide que dos procesos envíen el mismo manifiesto simultáneamente. Después de un fallo abrupto, elimina un .lock obsoleto solo tras confirmar que el PID almacenado en él ya no está en ejecución. Empieza con un elemento en curso. Aumenta un número de workers acotado solo después de medir la latencia de procesamiento y las respuestas de rate limit para tu cuenta. Reintenta errores de transporte y límites de tasa con backoff, respetando Retry-After. No reintentes a ciegas errores de validación, conflictos de temporización o fallos terminales de procesamiento. Los errores de autenticación requieren credenciales válidas; no significan que un trabajo de procesamiento haya fallado. Mantén el sondeo existente de tareas en la nube y el manejo de créditos por fallo. Aquí no se introduce ningún endpoint por lotes, promesa de webhook, cambio de precios, cambio de licencias ni política de retención.

Guides

API Reference

Automatizar videos con letras

Elegir un flujo de trabajo y un modelo

Crear y cotizar proyectos

Corregir tiempos sin trabajos de procesamiento

Exportar una versión elegida

Operar un catálogo de forma segura

​Elegir un flujo de trabajo y un modelo

​Crear y cotizar proyectos

​Corregir tiempos sin trabajos de procesamiento

​Exportar una versión elegida

​Operar un catálogo de forma segura

Elegir un flujo de trabajo y un modelo

Crear y cotizar proyectos

Corregir tiempos sin trabajos de procesamiento

Exportar una versión elegida

Operar un catálogo de forma segura