Перейти к основному содержанию
Youka спроектирован так, чтобы им управляли агенты. Каждая команда CLI возвращает машиночитаемый JSON-конверт, каждая операция записи поддерживает ключи идемпотентности, а публичный API предоставляет ту же поверхность с той же семантикой. На этой странице собраны правила эксплуатации, которые нужны автору агента перед тем, как встроить Youka в рабочий процесс.

​
Get started

Если вы настраиваете агента впервые, сначала установите Youka CLI, затем установите навык Youka karaoke: 
npm install -g @youka/cli
npx skills add https://github.com/youka-io/skills --skill youka-karaoke
Это даст агенту готовый навык Youka, работающий поверх CLI. После установки используйте шаблоны рабочих процессов ниже, чтобы создавать караоке-видео, настраивать стиль и безопасно экспортировать MP4-файлы.

​
Prompt your agent

После установки CLI и навыка вы можете дать агенту прямую задачу, например так: 
Используй Youka, чтобы создать караоке-видео из /path/to/song.mp3. Транскрибируй текст песни на английском, используй чистый стиль караоке-субтитров, экспортируй финальное видео в 1080p и сохрани как ./karaoke.mp4.

​
Operating rules

Always use --json

В CLI всегда передавайте --json. В API всегда устанавливайте Accept: application/json. Никогда не парсите человекочитаемый вывод.

Always send an idempotency key

Каждая операция записи должна содержать стабильный ключ идемпотентности, чтобы повтор после таймаута возвращал исходный результат вместо дублирования работы.

Re-read durable state

Не доверяйте устаревшим ответам на мутации. После завершения задачи перечитайте проект или экспорт, чтобы получить финальное состояние.

Poll with backoff

Начинайте с интервала 2–3 секунды. Экспоненциально увеличивайте интервал для длительных задач. Учитывайте ответы 429.

​
Output contract

Каждая команда CLI в режиме --json пишет ровно один конверт в stdout. Успех: 
{
  "schemaVersion": "1",
  "ok": true,
  "data": { "id": "prj_abc123", "title": "My Song" }
}
Ошибка: 
{
  "schemaVersion": "1",
  "ok": false,
  "error": {
    "code": "CONFLICT",
    "message": "A request with this Idempotency-Key is already in progress.",
    "retryable": true
  }
}
Коды завершения:
CodeMeaningRetry?
0Успех.N/A
1Ошибка выполнения (сеть, API, рендер).Проверьте error.retryable.
2Некорректный ввод (плохие флаги, нечитаемый payload).Нет — исправьте ввод.

​
End-to-end workflow

Канонический рабочий процесс агента: создать проект, дождаться, экспортировать, скачать результат. Ниже — полный шаблон с реализациями и для CLI, и для 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')"

​
Polling guidance

Большинство операций записи в SDK возвращают дескрипторы операций. Предпочитайте client.projects.wait(...) и client.exports.wait(...) и опускайтесь до client.tasks.* только когда вам явно нужен низкоуровневый доступ к задачам.
Job typeRecommended initial intervalMax wait
Создание проекта (stems + синхронизация текста)3 s15 min
Только разделение stems3 s10 min
Только синхронизация текста2 s5 min
Рендер экспорта3 s30 min
В CLI флаг --wait делает polling за вас. В SDK wait-хелперы по умолчанию используют интервал 2 s и принимают pollIntervalMs.
Учитывайте ответы 429. При rate limit делайте back off как минимум на значение заголовка Retry-After (или на 30 s, если его нет).

​
Idempotency keys

Каждая операция создания и обновления поддерживает ключ идемпотентности. Правила:
  • Используйте стабильный, уникальный, детерминированный ключ на одну логическую мутацию. Хорошо: create-song-${sourceHash}. Плохо: новый UUID на каждый повтор.
  • При повторах используйте тот же самый ключ. Сервер распознаёт повтор и возвращает исходный результат.
  • Ключи действуют в рамках одного аккаунта и истекают через 24 часа.
  • Если сервер возвращает IDEMPOTENT_REPLAY_IN_PROGRESS (HTTP 202), исходный запрос всё ещё выполняется. Подождите и повторите с тем же ключом.
Пример шаблона: 
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;
}
Полный контракт см. в API idempotency.

​
Error recovery

Ветвитесь по error.code и error.retryable. Частые случаи:
CodeCauseAction
INVALID_REQUESTТело запроса не прошло валидацию схемы.Исправьте payload. Без повтора.
UNAUTHORIZEDОтсутствует или неверный API key.Передайте вызывающей стороне. Без повтора.
NOT_FOUNDРесурс не существует или нет доступа.Без повтора.
CONFLICT (409)Конфликт версий или коллизия идемпотентности.Повторите с тем же ключом идемпотентности.
TOO_MANY_REQUESTS (429)Rate limit.Back off по Retry-After или 30 s.
INTERNAL_SERVER_ERROR (500)Временный сбой сервера.Повторить до 3 раз с backoff.
IDEMPOTENT_REPLAY_IN_PROGRESS (202)Предыдущий запрос всё ещё выполняется.Подождать и повторить с тем же ключом.
TASK_FAILEDАсинхронная задача завершилась неуспехом.Передайте error.task.error вызывающей стороне. Без повтора.
TASK_TIMED_OUTАсинхронная задача превысила лимит времени.Можно безопасно повторить один раз.

​
Discovering mutable fields

Перед изменением пресетов запросите схему пресета, чтобы модель знала допустимые поля и типы значений: 
# Preset body schema
youka preset schema --json
Для настроек проекта предпочтительно сначала читать текущие настройки проекта, а затем отправлять минимальное тело обновления через youka project settings <id> --body .... Запрашивайте один раз на сессию агента и кэшируйте результат.

​
Parallel agents

Когда несколько агентов работают параллельно в рамках одного аккаунта:
  • Делайте idempotency keys привязанными и к идентичности агента, и к логической мутации: agent-${agentId}-create-${sourceHash}. Это предотвращает коллизию повтора одного агента с новым запросом другого.
  • Оставляйте чтения неограниченными — GET-запросы дешёвые и не имеют побочных эффектов.
  • Используйте одну очередь для POST /projects/{projectId}/exports на проект, если вам нужна упорядоченная история экспортов. Иначе экспорты могут приходить не по порядку.

​
What’s next