@youka/sdk e @youka/cli versão 0.2.0 ou posterior para estes exemplos. Projetos criados pela API permanecem disponíveis na sua biblioteca do Youka.
Escolha um workflow e um modelo
kind seleciona o workflow do projeto. karaoke separa stems. lyric-video usa o áudio original e não cobra pela separação. Ao omitir kind, mantém-se o comportamento existente de karaoke. O processamento de letras é uma escolha separada entre alinhamento, transcrição ou nenhum processamento.
Descubra os modelos e a elegibilidade da conta antes de escolher um modelo.
suppliedTextHandling distingue alinhamento, termos-chave do provedor e correção após a transcrição. A elegibilidade reflete a conta autenticada. A descoberta descreve o suporte configurado, não uma garantia de disponibilidade do provedor. A validação da requisição e as cotações de preço continuam sendo a autoridade.
Modelos que exigem vocais isolados não conseguem processar um lyric video sem separação. Use-os em um workflow de karaoke com um modelo de separação que produza vocais. Wav2Vec2 é um modelo de alinhamento. ElevenLabs Scribe é um modelo de transcrição. Um texto de transcrição fornecido serve como orientação, não como garantia de saída textual idêntica.
Criar e cotar projetos
--kind ou passe --kind karaoke e escolha --split-model. Use --mode none para criar sem processamento de letras. Requisições de lyric-video rejeitam opções de separação.
Cote a mesma fonte, workflow e opções de processamento antes de criar.
Corrigir timings sem jobs de processamento
Leia alinhamentos viaGET /projects/{projectId}/alignments, depois obtenha o recurso escolhido via GET /projects/{projectId}/alignments/{alignmentId}. A lista contém alignments, selectedAlignmentId e selectionRevision. Cada recurso inclui o payload de timing, revision, selected e selectionRevision.
Atualizações substituem o objeto alignment completo. Elas não executam sincronização nem criam uma retenção de créditos de processamento. Ao editar, mantenha IDs, texto, índices de linha/palavra/subpalavra, informações do cantor e traduções. Os tempos são segundos decimais absolutos. Aplique qualquer correção desejada uma única vez nos valores enviados. Não adicione a mesma correção novamente como um offset de exportação.
select: true para salvar e selecionar de forma atômica. Para selecionar timings existentes sem substituí-los, chame client.projects.alignments.select(projectId, alignmentId, { expectedRevision, expectedSelectionRevision }).
A revisão do alinhamento protege o conteúdo dos timings. A revisão de seleção protege qual alinhamento está ativo. Um token desatualizado produz HTTP 409. Busque o recurso mais recente, compare as edições e envie uma substituição deliberada. Não atualize automaticamente o token e sobrescreva as alterações de outro editor.
A CLI aceita um arquivo JSON ou a entrada padrão. Um arquivo de importação contém { "alignment": { "items": [...] }, "expectedRevision": "..." }. Inclua select e expectedSelectionRevision ao selecionar de forma atômica. Recursos exportados também contêm metadados de resposta, então extraia os campos de requisição antes de importar.
Exportar uma versão escolhida
versionId é opcional em requisições de exportação e atualizações de configurações, e na query do GET de configurações. Ao omiti-lo, mantém-se o comportamento de versão primária. O alinhamento selecionado pertence ao projeto, enquanto o estilo e as configurações pertencem à versão escolhida.
versionId, alignmentId e alignmentRevision. Esses campos identificam o snapshot de timing usado para aquela exportação ou payload preparado. Cada preparação lê o estado atual, então uma exportação posterior separada pode observar edições mais novas. Salve o payload retornado quando um renderizador externo precisar renderizar exatamente aquele snapshot preparado e atualize-o quando URLs de mídia assinadas expirarem.
A saída local transparente usa ProRes 4444 em um contêiner MOV. --mute-all mapeia todos os stems do projeto para volume zero. Silêncio e a ausência de um stream de áudio são propriedades de saída diferentes; inspecione o arquivo renderizado se uma ferramenta downstream exigir uma delas. A renderização local não consome créditos de exportação na nuvem e continua sujeita à elegibilidade de recursos existente.
Timing de palavras, offsets globais de áudio e antecipação de letras são configurações separadas. Layouts existentes controlam a visibilidade das linhas. Esta versão não promete um intervalo fixo de revelação para cada linha nem adiciona uma API separada de anexação de backing track.
Operar um catálogo com segurança
Mantenha um manifesto com um ID de item estável, fingerprint da fonte, configurações da operação, chave de idempotência, IDs de projeto/tarefa e o último resultado terminal. Reutilize uma chave apenas para retries da mesma requisição. Persista os resultados de criação antes de esperar a conclusão, para que um restart possa retomar o polling. Uploads e preparação de arquivos locais têm seu próprio ciclo de vida; uma chave de idempotência de criação não deduplica todo upload. O executável exemplo de catálogo aceita IDs de arquivos de entrada pré-enviados e persiste um checkpoint por item. Um manifesto se parece com isto.catalogue.ts. Instale suas dependências e defina YOUKA_API_KEY. Use um projeto Node.js com "type": "module" no seu package.json.
.lock obsoleto apenas depois de confirmar que o PID armazenado nele não está mais em execução.
Comece com um item em andamento. Aumente um número de workers limitado somente após medir a latência de processamento e as respostas de rate-limit da sua conta. Faça retry de erros de transporte e rate limits com backoff, respeitando Retry-After. Não faça retry cegamente de erros de validação, conflitos de timing ou falhas terminais de processamento. Erros de autenticação exigem credenciais válidas; eles não significam que um job de processamento falhou.
Mantenha o polling existente de tarefas na nuvem e o tratamento de créditos em falhas. Nenhum endpoint em lote, promessa de webhook, mudança de preços, mudança de licenciamento ou política de retenção é introduzido aqui.