Projects

Los proyectos son el recurso de nivel superior en Youka. Cada proyecto posee su archivo de origen, letras, exportaciones y ajustes del proyecto. Los proyectos de karaoke también contienen stems separados.

Creación de un proyecto

En la mayoría de los casos, usa client.projects.create() — gestiona las subidas por ti.

const operation = await client.projects.create({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: { type: "transcribe" },
});
// => ProjectOperation

Tipos de fuente

path
bytes
url

Lee un archivo desde el disco.

source: {
  type: "path",
  path: "./song.mp3",
  contentType: "audio/mpeg", // optional, inferred if omitted
}

Blob, File, ArrayBuffer o Uint8Array en memoria.

source: {
  type: "bytes",
  data: fileBuffer,
  filename: "song.mp3",
  contentType: "audio/mpeg", // optional
}

URL HTTP o HTTPS remota.Las páginas alojadas compatibles dependen de yt-dlp. Consulta la lista de URLs compatibles.

source: {
  type: "url",
  url: "https://example.com/song.mp4",
  maxVideoQuality: "1080p", // optional: "720p", "1080p", "4k", or "best"
}

maxVideoQuality controla la calidad máxima del video descargado para las fuentes URL. Por defecto es 1080p. El SDK usa la mejor calidad disponible hasta ese límite, y recurre al mejor formato disponible si la plataforma no expone un stream con límite. Usa best para no imponer límite.

En Node.js y Bun, el SDK asegura automáticamente los binarios de dependencias de URL requeridos (ffmpeg, ffprobe, yt-dlp) en el primer uso. El equivalente en la CLI es youka deps ensure --for url.

Otros campos

string

Título del proyecto. Por defecto, el nombre de archivo de la fuente.

karaoke | lyric-video

Flujo de trabajo. Por defecto, karaoke. lyric-video usa el audio original sin separación de stems.

SplitModel

Modelo de separación de stems para karaoke. Por defecto, mdx23c. Se rechaza para lyric-video. Consulta la referencia de modelos de split.

string

Aplica un preset reutilizable en el momento de la creación.

LyricsSource

Configura la sincronización de letras. Ver abajo.

Fuentes de letras

// Transcribe lyrics from the audio
lyricsSource: {
  type: "transcribe",
  syncModel: "audioshake-transcription", // optional
  language: "en",                        // optional
}

// Align exact lyrics to the audio
lyricsSource: {
  type: "align",
  lyrics: "First line\nSecond line\n...",
  syncModel: "audioshake-alignment",
}

`client.projects.create(input, options?)`

client.projects.create() también acepta una fuente inputFile de bajo nivel cuando ya tienes un inputFileId subido.

const upload = await client.uploads.create({
  filename: "song.mp3",
  contentType: "audio/mpeg",
  contentLength: buffer.byteLength,
});

await client.uploads.upload(upload.uploadUrl, buffer, {
  contentType: "audio/mpeg",
});

const operation = await client.projects.create({
  source: {
    type: "inputFile",
    inputFileId: upload.inputFileId,
    filename: "song.mp3",
  },
  title: "My Song",
});

`client.projects.quote(input, options?)`

Cotiza los créditos necesarios para crear un proyecto sin crearlo.

const quote = await client.projects.quote({
  source: { type: "path", path: "./song.mp3" },
  lyricsSource: { type: "transcribe", language: "en" },
  splitModel: "mdx23c",
});

console.log(quote.creditsRequired, quote.sufficientBalance);

client.projects.quote(...) acepta las mismas formas de source que client.projects.create(...), incluido maxVideoQuality para URL. Si ya conoces la duración del medio y no quieres subir el archivo solo para cotizar, pasa la forma REST de bajo nivel:

const quote = await client.projects.quote({
  durationSeconds: 210,
  lyricsSource: null,
  splitModel: "mdx23c",
});

`client.uploads.create(body, options?)`

Reserva un slot de subida y obtiene una URL firmada.

const upload = await client.uploads.create({
  filename: "song.mp3",
  contentType: "audio/mpeg",
  contentLength: 4_521_344,
});
// => { inputFileId, uploadUrl }

`client.uploads.upload(uploadUrl, body, options?)`

Haz PUT de los bytes del archivo a la URL firmada.

await client.uploads.upload(upload.uploadUrl, fileBuffer, {
  contentType: "audio/mpeg",
  signal: abortController.signal,
});

FetchBody

required

Cualquier body compatible con fetch: Blob, File, ArrayBuffer, Uint8Array, ReadableStream o string.

Lanza YoukaRequestError con el código UPLOAD_FAILED si la subida devuelve un estado no 2xx.

`client.projects.get(projectId, options?)`

Obtén el estado completo del proyecto, incluidos stems, letras y exportaciones.

const project = await client.projects.get("prj_abc123");
console.log(project.title, project.stems, project.lyrics);

`client.projects.update(projectId, body, options?)`

Aplica un patch a los metadatos del proyecto.

const project = await client.projects.update("prj_abc123", {
  title: "Updated title",
  artists: ["Artist name"],
});

Pasa al menos uno de title o artists.

`client.projects.list(options?)`

Lista todos los proyectos propiedad de la cuenta autenticada.

const projects = await client.projects.list();
projects.forEach((p) => console.log(p.id, p.title));

Devuelve un array de elementos de lista de proyectos (una forma más ligera que getProject).

`client.projects.delete(projectId, options?)`

Elimina un proyecto y todos sus stems, letras y exportaciones asociados.

await client.projects.delete("prj_abc123", {
  idempotencyKey: "delete-prj_abc123",
});

La eliminación es permanente. Acompáñalo con una clave de idempotencia para que los reintentos sean seguros.

Qué sigue

Stems — volver a ejecutar la separación de stems
Lyrics sync — volver a sincronizar letras
Exports — renderizar videos terminados
Tasks — esperar operaciones de proyecto con client.projects.wait

Creación de lyric-video y descubrimiento de modelos

const capabilities = await client.capabilities.get();
const operation = await client.projects.create({
  kind: "lyric-video",
  source: { type: "path", path: "./song.wav" },
  lyricsSource: {
    type: "transcribe",
    syncModel: "elevenlabs-transcription",
    lyrics: "Optional reference lyrics",
  },
});
const { project } = await client.projects.wait(operation);
const versions = await client.projects.versions.list(project.id);

Las mismas opciones de kind y de procesamiento de letras funcionan con projects.quote. Las cotizaciones de lyric-video cobran cero créditos de separación. Tanto quote como create validan los mismos requisitos de modelo, idioma, cuenta y fuente. Las cotizaciones no reservan créditos ni capacidad. Usa lyricsSource: null para omitir el procesamiento de letras. El texto de referencia en la transcripción sirve como guía y puede diferir del resultado. Los modelos que requieren voces aisladas no pueden procesar un lyric video sin separación. Consulta Automate lyric videos para capacidades, actualizaciones de timing exactas y checkpoints del catálogo.

Overview

How To

Customization

Audio

Settings

Exporting

Account

Creación de un proyecto

Tipos de fuente

Otros campos

Fuentes de letras

`client.projects.create(input, options?)`

`client.projects.quote(input, options?)`

`client.uploads.create(body, options?)`

`client.uploads.upload(uploadUrl, body, options?)`

`client.projects.get(projectId, options?)`

`client.projects.update(projectId, body, options?)`

`client.projects.list(options?)`

`client.projects.delete(projectId, options?)`

Qué sigue

Creación de lyric-video y descubrimiento de modelos

​Creación de un proyecto

​Tipos de fuente

​Otros campos

​Fuentes de letras

​client.projects.create(input, options?)

​client.projects.quote(input, options?)

​client.uploads.create(body, options?)

​client.uploads.upload(uploadUrl, body, options?)

​client.projects.get(projectId, options?)

​client.projects.update(projectId, body, options?)

​client.projects.list(options?)

​client.projects.delete(projectId, options?)

​Qué sigue

​Creación de lyric-video y descubrimiento de modelos

Creación de un proyecto

Tipos de fuente

Otros campos

Fuentes de letras

`client.projects.create(input, options?)`

`client.projects.quote(input, options?)`

`client.uploads.create(body, options?)`

`client.uploads.upload(uploadUrl, body, options?)`

`client.projects.get(projectId, options?)`

`client.projects.update(projectId, body, options?)`

`client.projects.list(options?)`

`client.projects.delete(projectId, options?)`

Qué sigue

Creación de lyric-video y descubrimiento de modelos