Projetos

Projects são o recurso de nível mais alto no Youka. Cada project é dono do seu arquivo de origem, letras, exportações e configurações do projeto. Projetos de karaokê também contêm stems separados.

Criando um projeto

Na maioria dos casos, use client.projects.create() — ele faz os uploads para você.

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

Tipos de source

path
bytes
url

Lê um arquivo do disco.

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

Blob, File, ArrayBuffer ou Uint8Array em memória.

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

URL remota HTTP ou HTTPS.As páginas hospedadas suportadas dependem do yt-dlp. Veja a lista de URLs suportadas.

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

maxVideoQuality controla a qualidade máxima de vídeo baixada para sources do tipo URL. O padrão é 1080p. O SDK usa a melhor qualidade disponível até esse limite e faz fallback para o melhor formato disponível se a plataforma não expuser um stream com limite. Use best para não impor limite.

No Node.js e no Bun, o SDK garante automaticamente os binários de dependência de URL necessários (ffmpeg, ffprobe, yt-dlp) no primeiro uso. O equivalente na CLI é youka deps ensure --for url.

Outros campos

string

Título do projeto. O padrão é o nome do arquivo de origem.

karaoke | lyric-video

Fluxo de trabalho. O padrão é karaoke. lyric-video usa o áudio original sem separação de stems.

SplitModel

Modelo de separação de stems para karaoke. O padrão é mdx23c. Rejeitado para lyric-video. Veja a referência de modelo de split .

string

Aplica um preset reutilizável no momento da criação.

LyricsSource

Configure a sincronização de letras. Veja abaixo.

Sources 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() também aceita um source inputFile de baixo nível quando você já tem um inputFileId enviado.

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?)`

Cote os créditos necessários para criar um projeto sem criá-lo.

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(...) aceita as mesmas formas de source que client.projects.create(...), incluindo URL maxVideoQuality. Se você já souber a duração da mídia e não quiser enviar o arquivo apenas para cotar, passe o formato REST de baixo nível:

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

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

Aloque um slot de upload e obtenha uma URL assinada.

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

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

Faça PUT dos bytes do arquivo para a URL assinada.

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

FetchBody

required

Qualquer body compatível com fetch: Blob, File, ArrayBuffer, Uint8Array, ReadableStream ou string.

Lança YoukaRequestError com o código UPLOAD_FAILED se o upload retornar um status não-2xx.

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

Busque o estado completo do projeto, incluindo stems, letras e exportações.

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

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

Aplique patch nos metadados do projeto.

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

Passe pelo menos um entre title ou artists.

`client.projects.list(options?)`

Liste todos os projetos pertencentes à conta autenticada.

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

Retorna um array de itens de listagem de projetos (um formato mais enxuto do que getProject).

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

Exclua um projeto e todos os seus stems, letras e exportações associados.

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

A exclusão é permanente. Use junto com uma chave de idempotência para que tentativas de repetição sejam seguras.

Próximos passos

Stems — execute novamente a separação de stems
Lyrics sync — sincronize as letras novamente
Exports — renderize vídeos finalizados
Tasks — aguarde operações do projeto com client.projects.wait

Criação de lyric-video e descoberta 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);

As mesmas escolhas de kind e de processamento de letras funcionam com projects.quote. Cotações de lyric-video cobram zero créditos de separação. Quote e create validam os mesmos requisitos de modelo, idioma, conta e source. Cotações não reservam créditos nem capacidade. Use lyricsSource: null para pular o processamento de letras. O texto de referência na transcrição serve como orientação e pode diferir do resultado. Modelos que precisam de vocais isolados não conseguem processar um lyric video sem separação. Veja Automate lyric videos para capacidades, atualizações de timing exato e checkpoints do catálogo.

Overview

How To

Customization

Audio

Settings

Exporting

Account

Criando um projeto

Tipos de source

Outros campos

Sources 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?)`

Próximos passos

Criação de lyric-video e descoberta de modelos

​Criando um projeto

​Tipos de source

​Outros campos

​Sources 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?)

​Próximos passos

​Criação de lyric-video e descoberta de modelos

Criando um projeto

Tipos de source

Outros campos

Sources 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?)`

Próximos passos

Criação de lyric-video e descoberta de modelos