Agenti AI - Youka Docs

Youka è progettato per essere guidato da agenti. Ogni comando CLI restituisce una busta JSON leggibile dalle macchine, ogni operazione di scrittura supporta chiavi di idempotenza e l’API pubblica espone la stessa superficie con la stessa semantica. Questa pagina raccoglie le regole operative di cui un autore di agenti ha bisogno prima di integrare Youka in un workflow.

Per iniziare

Se stai configurando un agente per la prima volta, installa prima la Youka CLI, poi installa la skill karaoke di Youka:

npm install -g @youka/cli
npx skills add https://github.com/youka-io/skills --skill youka-karaoke

Questo fornisce all’agente una skill Youka pronta all’uso, basata sulla CLI. Una volta installata, usa i pattern di workflow qui sotto per creare video karaoke, personalizzare lo stile ed esportare file MP4 in modo sicuro.

Dai un prompt al tuo agente

Dopo aver installato CLI e skill, puoi assegnare al tuo agente un compito diretto come questo:

Usa Youka per creare un video karaoke da /path/to/song.mp3. Trascrivi i testi in inglese, usa uno stile di sottotitoli karaoke pulito, esporta il video finale in 1080p e salvalo come ./karaoke.mp4.

Regole operative

Usa sempre --json

Nella CLI, passa sempre --json. Nell’API, imposta sempre Accept: application/json. Non interpretare mai output pensato per gli esseri umani.

Invia sempre una chiave di idempotenza

Ogni scrittura dovrebbe includere una chiave di idempotenza stabile, così i tentativi dopo un timeout restituiscono il risultato originale invece di duplicare il lavoro.

Rileggi lo stato persistente

Non fidarti di risposte di mutazione obsolete. Dopo un task terminale, rileggi il progetto o l’export per ottenere lo stato finale.

Esegui polling con backoff

Inizia con un intervallo di 2–3 secondi. Applica backoff esponenziale per job lunghi. Rispetta le risposte 429.

Contratto di output

Ogni comando CLI in modalità --json scrive esattamente una busta su stdout. Successo:

{
  "schemaVersion": "1",
  "ok": true,
  "data": { "id": "prj_abc123", "title": "My Song" }
}

Errore:

{
  "schemaVersion": "1",
  "ok": false,
  "error": {
    "code": "CONFLICT",
    "message": "A request with this Idempotency-Key is already in progress.",
    "retryable": true
  }
}

Codici di uscita:

Code	Meaning	Retry?
`0`	Successo.	N/A
`1`	Errore runtime (rete, API, rendering).	Controlla `error.retryable`.
`2`	Input non valido (flag errati, payload illeggibile).	No — correggi l’input.

Workflow end-to-end

Il workflow canonico dell’agente è: creare un progetto, attendere, esportare, scaricare il risultato. Ecco il pattern completo con implementazioni sia CLI sia 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')"

Linee guida per il polling

La maggior parte delle operazioni di scrittura restituisce handle di operazioni nell’SDK. Preferisci client.projects.wait(...) e client.exports.wait(...) e scendi a client.tasks.* solo quando ti serve esplicitamente un accesso a basso livello ai task.

Job type	Recommended initial interval	Max wait
Creazione progetto (stems + sync testi)	3 s	15 min
Solo separazione stems	3 s	10 min
Solo sync testi	2 s	5 min
Render export	3 s	30 min

Nella CLI, --wait gestisce il polling per te. Nell’SDK, gli helper di attesa usano un intervallo di 2 s per impostazione predefinita e accettano pollIntervalMs.

Rispetta le risposte 429. In caso di rate limit, applica backoff di almeno il valore dell’header Retry-After (o 30 s se assente).

Chiavi di idempotenza

Ogni operazione di creazione e aggiornamento supporta una chiave di idempotenza. Regole:

Usa una chiave stabile, unica, deterministica per ogni mutazione logica. Bene: create-song-${sourceHash}. Male: un UUID nuovo a ogni tentativo.
Riutilizza la stessa chiave tra i retry. Il server riconosce il replay e restituisce il risultato originale.
Le chiavi sono con scope per account e scadono dopo 24 ore.
Se il server restituisce IDEMPOTENT_REPLAY_IN_PROGRESS (HTTP 202), la richiesta originale è ancora in esecuzione. Attendi e riprova con la stessa chiave.

Pattern di esempio:

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;
}

Vedi API idempotency per il contratto completo.

Recupero dagli errori

Fai branching su error.code e error.retryable. I casi comuni:

Code	Cause	Action
`INVALID_REQUEST`	Il body della richiesta non ha superato la validazione dello schema.	Correggi il payload. Nessun retry.
`UNAUTHORIZED`	API key mancante o non valida.	Mostralo al chiamante. Nessun retry.
`NOT_FOUND`	La risorsa non esiste o non hai accesso.	Nessun retry.
`CONFLICT` (409)	Conflitto di versione o collisione di idempotenza.	Riprova con la stessa chiave di idempotenza.
`TOO_MANY_REQUESTS` (429)	Rate limit.	Back off di `Retry-After` o 30 s.
`INTERNAL_SERVER_ERROR` (500)	Errore transitorio del server.	Riprova fino a 3 volte con backoff.
`IDEMPOTENT_REPLAY_IN_PROGRESS` (202)	La richiesta precedente è ancora in esecuzione.	Attendi e riprova con la stessa chiave.
`TASK_FAILED`	Il task asincrono è terminato con errore.	Mostra `error.task.error` al chiamante. Nessun retry.
`TASK_TIMED_OUT`	Il task asincrono ha superato il tempo previsto.	Sicuro riprovare una volta.

Scoperta dei campi modificabili

Prima di modificare i preset, recupera lo schema del preset così il modello conosce i campi validi e i tipi di valore:

# Preset body schema
youka preset schema --json

Per le impostazioni del progetto, è preferibile leggere prima le impostazioni correnti del progetto, poi inviare un body di aggiornamento minimo tramite youka project settings <id> --body .... Recupera una sola volta per sessione dell’agente e memorizza in cache il risultato.

Agenti in parallelo

Quando più agenti vengono eseguiti in contemporanea sullo stesso account:

Applica lo scope delle chiavi di idempotenza sia all’identità dell’agente sia alla mutazione logica: agent-${agentId}-create-${sourceHash}. Questo impedisce che il retry di un agente collida con una richiesta nuova di un altro agente.
Mantieni le letture senza vincoli — le richieste GET sono economiche e non hanno effetti collaterali.
Usa una singola coda per POST /projects/{projectId}/exports per progetto se ti serve una cronologia degli export ordinata. Altrimenti gli export possono arrivare fuori ordine.

Cosa fare dopo

CLI global options — tutti i flag disponibili per gli agenti
SDK errors — riferimento completo alle classi di errore
API async jobs — il contratto di polling
API idempotency — il contratto di idempotenza

Overview

​Per iniziare

​Dai un prompt al tuo agente

​Regole operative

Usa sempre --json

Invia sempre una chiave di idempotenza

Rileggi lo stato persistente

Esegui polling con backoff

​Contratto di output

​Workflow end-to-end

​Linee guida per il polling

​Chiavi di idempotenza

​Recupero dagli errori

​Scoperta dei campi modificabili

​Agenti in parallelo

​Cosa fare dopo

Per iniziare

Dai un prompt al tuo agente

Regole operative

Contratto di output

Workflow end-to-end

Linee guida per il polling

Chiavi di idempotenza

Recupero dagli errori

Scoperta dei campi modificabili

Agenti in parallelo

Cosa fare dopo