Saltar para o conteúdo principal
A Youka foi projetada para ser conduzida por agentes. Todo comando da CLI retorna um envelope JSON legível por máquina, toda escrita oferece suporte a chaves de idempotência e a API pública expõe a mesma superfície com a mesma semântica. Esta página reúne as regras operacionais de que um autor de agentes precisa antes de conectar a Youka a um workflow.

​
Primeiros passos

Se você estiver configurando um agente pela primeira vez, instale primeiro a Youka CLI e, em seguida, instale a skill de karaokê da Youka: 
npm install -g @youka/cli
npx skills add https://github.com/youka-io/skills --skill youka-karaoke
Isso fornece ao agente uma skill pronta da Youka apoiada na CLI. Depois de instalada, use os padrões de workflow abaixo para criar vídeos de karaokê, personalizar o estilo e exportar arquivos MP4 com segurança.

​
Instrua seu agente

Após instalar a CLI e a skill, você pode dar ao seu agente uma tarefa direta como esta: 
Use Youka to create a karaoke video from /path/to/song.mp3. Transcribe the lyrics in English, use a clean karaoke subtitle style, export the final video in 1080p, and save it as ./karaoke.mp4.

​
Regras operacionais

Sempre use --json

Na CLI, sempre passe --json. Na API, sempre defina Accept: application/json. Nunca faça parse de saída humana.

Sempre envie uma chave de idempotência

Toda escrita deve levar uma chave de idempotência estável para que novas tentativas após um timeout retornem o resultado original em vez de duplicar trabalho.

Releia o estado durável

Não confie em respostas de mutação desatualizadas. Após uma tarefa terminal, releia o projeto ou a exportação para obter o estado final.

Faça polling com backoff

Comece com um intervalo de 2–3 segundos. Aplique backoff exponencial para jobs longos. Respeite respostas 429.

​
Contrato de saída

Todo comando da CLI no modo --json escreve exatamente um envelope no stdout. Sucesso: 
{
  "schemaVersion": "1",
  "ok": true,
  "data": { "id": "prj_abc123", "title": "My Song" }
}
Falha: 
{
  "schemaVersion": "1",
  "ok": false,
  "error": {
    "code": "CONFLICT",
    "message": "A request with this Idempotency-Key is already in progress.",
    "retryable": true
  }
}
Códigos de saída:
CodeMeaningRetry?
0Sucesso.N/A
1Erro de runtime (rede, API, renderização).Verifique error.retryable.
2Entrada inválida (flags ruins, payload ilegível).Não — corrija a entrada.

​
Workflow de ponta a ponta

O workflow canônico do agente é: criar um projeto, aguardar, exportar, baixar o resultado. Aqui está o padrão completo com implementações em CLI e SDK. 
# 1. Create the project and wait for stems + lyrics sync to finish
PROJECT_JSON=$(youka project create ./song.mp3 \
  --mode transcribe \
  --lang en \
  --wait \
  --idempotency-key "create-song-2026-04-08-001" \
  --json)

PROJECT_ID=$(echo "$PROJECT_JSON" | jq -r '.data.projectId')

# 2. Start and wait for an export
EXPORT_JSON=$(youka export create "$PROJECT_ID" \
  --resolution 1080p \
  --quality high \
  --wait \
  --download \
  --output ./karaoke.mp4 \
  --idempotency-key "export-$PROJECT_ID-v1" \
  --json)

echo "Done:" "$(echo "$EXPORT_JSON" | jq -r '.data.fileUrl')"

​
Orientações de polling

A maioria das escritas retorna handles de operação no SDK. Prefira client.projects.wait(...) e client.exports.wait(...) e recorra a client.tasks.* apenas quando você precisar explicitamente de acesso a tasks de baixo nível.
Job typeRecommended initial intervalMax wait
Criação de projeto (stems + sync de letras)3 s15 min
Apenas separação de stems3 s10 min
Apenas sync de letras2 s5 min
Render de exportação3 s30 min
Na CLI, --wait cuida do polling para você. No SDK, os helpers de wait usam um intervalo de 2 s por padrão e aceitam pollIntervalMs.
Respeite respostas 429. Em rate limits, aplique backoff de pelo menos o header Retry-After (ou 30 s se estiver ausente).

​
Chaves de idempotência

Toda operação de criação e atualização suporta uma chave de idempotência. Regras:
  • Use uma chave estável, única e determinística por mutação lógica. Bom: create-song-${sourceHash}. Ruim: um UUID novo a cada retry.
  • Reuse a mesma chave em novas tentativas. O servidor reconhece o replay e retorna o resultado original.
  • As chaves têm escopo por conta e expiram após 24 horas.
  • Se o servidor retornar IDEMPOTENT_REPLAY_IN_PROGRESS (HTTP 202), a requisição original ainda está em execução. Aguarde e tente novamente com a mesma chave.
Padrão de exemplo: 
const key = `create-${sha256(sourceBytes)}`;

try {
  return await client.projects.create(body, { idempotencyKey: key });
} catch (error) {
  if (error instanceof YoukaRequestError && error.retryable) {
    // Safe to retry with the same key
    return await client.projects.create(body, { idempotencyKey: key });
  }
  throw error;
}
Veja API idempotency para o contrato completo.

​
Recuperação de erros

Faça branch com base em error.code e error.retryable. Os casos comuns:
CodeCauseAction
INVALID_REQUESTO corpo da requisição falhou na validação do schema.Corrija o payload. Sem retry.
UNAUTHORIZEDChave de API ausente ou inválida.Exiba ao chamador. Sem retry.
NOT_FOUNDO recurso não existe ou você não tem acesso.Sem retry.
CONFLICT (409)Conflito de versão ou colisão de idempotência.Tente novamente com a mesma chave de idempotência.
TOO_MANY_REQUESTS (429)Rate limit.Aplique backoff por Retry-After ou 30 s.
INTERNAL_SERVER_ERROR (500)Falha transitória no servidor.Retry até 3 vezes com backoff.
IDEMPOTENT_REPLAY_IN_PROGRESS (202)Requisição anterior ainda em execução.Aguarde e tente novamente com a mesma chave.
TASK_FAILEDA task assíncrona terminou em falha.Exiba error.task.error ao chamador. Sem retry.
TASK_TIMED_OUTA task assíncrona excedeu seu orçamento.Seguro tentar novamente uma vez.

​
Descobrindo campos mutáveis

Antes de mutar presets, busque o schema do preset para que o modelo conheça os campos válidos e os tipos de valor: 
# Preset body schema
youka preset schema --json
Para configurações de projeto, prefira ler primeiro as configurações atuais do projeto e, em seguida, enviar um corpo mínimo de update por meio de youka project settings <id> --body .... Busque uma vez por sessão do agente e faça cache do resultado.

​
Agentes em paralelo

Quando vários agentes executam simultaneamente na mesma conta:
  • Defina o escopo das chaves de idempotência para ambos: a identidade do agente e a mutação lógica: agent-${agentId}-create-${sourceHash}. Isso evita que o retry de um agente colida com a requisição nova de outro agente.
  • Mantenha leituras sem limites — requisições GET são baratas e não têm efeitos colaterais.
  • Use uma única fila para POST /projects/{projectId}/exports por projeto se você precisar de histórico de exportações ordenado. Caso contrário, as exportações podem chegar fora de ordem.

​
Próximos passos