메인 콘텐츠로 건너뛰기
Youka는 에이전트가 구동하도록 설계되었습니다. 모든 CLI 명령은 기계가 읽을 수 있는 JSON 엔벨로프를 반환하고, 모든 쓰기 작업은 멱등성 키를 지원하며, 공개 API는 동일한 의미 체계로 동일한 표면을 노출합니다. 이 페이지는 Youka를 워크플로에 연결하기 전에 에이전트 작성자가 알아야 할 운영 규칙을 모아둡니다.

​
시작하기

에이전트를 처음 설정한다면, 먼저 Youka CLI를 설치한 다음 Youka karaoke 스킬을 설치하세요: 
npm install -g @youka/cli
npx skills add https://github.com/youka-io/skills --skill youka-karaoke
이렇게 하면 CLI로 구동되는 готов된(기성) Youka 스킬이 에이전트에 제공됩니다. 설치가 끝나면 아래의 워크플로 패턴을 사용해 가라오케 비디오를 만들고, 스타일을 커스터마이즈하고, MP4 파일을 안전하게 내보낼 수 있습니다.

​
에이전트에 프롬프트 주기

CLI와 스킬을 설치한 뒤에는, 에이전트에 다음처럼 직접 작업을 지시할 수 있습니다: 
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.

​
운영 규칙

항상 --json 사용

CLI에서는 항상 --json을 전달하세요. API에서는 항상 Accept: application/json을 설정하세요. 사람이 읽는 출력은 절대 파싱하지 마세요.

항상 멱등성 키 전송

모든 쓰기 작업에는 안정적인 멱등성 키를 포함해야 하며, 타임아웃 이후 재시도하더라도 작업이 중복 생성되지 않고 원래 결과를 반환해야 합니다.

영속 상태를 다시 읽기

오래된 변경 응답을 신뢰하지 마세요. 종료(terminal)된 작업 이후에는 최종 상태를 얻기 위해 프로젝트 또는 익스포트를 다시 읽으세요.

백오프로 폴링

2–3초 간격으로 시작하세요. 긴 작업은 지수적으로 백오프하세요. 429 응답을 준수하세요.

​
출력 계약

--json 모드에서 모든 CLI 명령은 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잘못된 입력(잘못된 플래그, 읽을 수 없는 페이로드).아니오 — 입력을 수정하세요.

​
엔드-투-엔드 워크플로

정석(캐노니컬) 에이전트 워크플로는 다음과 같습니다: 프로젝트 생성, 대기, 익스포트, 결과 다운로드. 아래는 CLI와 SDK 구현을 모두 포함한 전체 패턴입니다. 
# 1. 프로젝트를 생성하고 stems + lyrics sync가 끝날 때까지 대기
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. 익스포트를 시작하고 완료될 때까지 대기
EXPORT_JSON=$(youka export create "$PROJECT_ID" \
  --resolution 1080p \
  --quality high \
  --wait \
  --download \
  --output ./karaoke.mp4 \
  --idempotency-key "export-$PROJECT_ID-v1" \
  --json)

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

​
폴링 가이드

대부분의 쓰기 작업은 SDK에서 operation handle을 반환합니다. client.projects.wait(...) 및 client.exports.wait(...)를 우선 사용하고, 명시적으로 저수준 task 접근이 필요할 때만 client.tasks.*로 내려가세요.
Job typeRecommended initial intervalMax wait
Project create (stems + lyrics sync)3 s15 min
Stem separation only3 s10 min
Lyrics sync only2 s5 min
Export render3 s30 min
CLI에서는 --wait가 폴링을 대신 처리합니다. SDK에서는 wait helper가 기본으로 2 s 간격을 사용하며 pollIntervalMs를 받습니다.
429 응답을 준수하세요. 레이트 리밋이 걸리면 Retry-After 헤더(없으면 30 s) 이상으로 백오프하세요.

​
멱등성 키

모든 생성 및 업데이트 작업은 멱등성 키를 지원합니다. 규칙:
  • 논리적 변경(mutation) 단위로 안정적이고, 유일하며, 결정적인 키를 사용하세요. 좋음: 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) {
    // 동일한 키로 안전하게 재시도 가능
    return await client.projects.create(body, { idempotencyKey: key });
  }
  throw error;
}
전체 계약은 API idempotency를 참고하세요.

​
오류 복구

error.code와 error.retryable을 기준으로 분기하세요. 흔한 케이스:
CodeCauseAction
INVALID_REQUEST요청 바디가 스키마 검증에 실패했습니다.페이로드를 수정하세요. 재시도 없음.
UNAUTHORIZEDAPI 키가 없거나 유효하지 않습니다.호출자에게 전달하세요. 재시도 없음.
NOT_FOUND리소스가 없거나 접근 권한이 없습니다.재시도 없음.
CONFLICT (409)버전 충돌 또는 멱등성 충돌.동일한 멱등성 키로 재시도하세요.
TOO_MANY_REQUESTS (429)레이트 리밋.Retry-After 또는 30 s 기준으로 백오프하세요.
INTERNAL_SERVER_ERROR (500)일시적인 서버 장애.백오프와 함께 최대 3회 재시도하세요.
IDEMPOTENT_REPLAY_IN_PROGRESS (202)이전 요청이 아직 실행 중입니다.기다렸다가 동일한 키로 재시도하세요.
TASK_FAILED비동기 작업이 실패로 종료되었습니다.error.task.error를 호출자에게 전달하세요. 재시도 없음.
TASK_TIMED_OUT비동기 작업이 제한 시간을 초과했습니다.1회 재시도는 안전합니다.

​
변경 가능한 필드 찾기

프리셋을 변경하기 전에 프리셋 스키마를 가져와서 모델이 유효한 필드와 값 타입을 알 수 있도록 하세요: 
# Preset body schema
youka preset schema --json
프로젝트 설정의 경우, 먼저 현재 프로젝트 설정을 읽은 다음 youka project settings <id> --body ...를 통해 최소한의 업데이트 바디만 제출하는 방식을 권장합니다. 에이전트 세션당 한 번만 가져오고 결과를 캐시하세요.

​
병렬 에이전트

여러 에이전트가 동일 계정에 대해 동시에 실행될 때:
  • 멱등성 키를 에이전트 ID와 논리적 변경 둘 다에 스코프하세요: agent-${agentId}-create-${sourceHash}. 이렇게 하면 한 에이전트의 재시도가 다른 에이전트의 새 요청과 충돌하는 것을 방지합니다.
  • 읽기 작업은 제한 없이 수행하세요 — GET 요청은 비용이 저렴하고 부작용이 없습니다.
  • 정렬된 익스포트 히스토리가 필요하다면 프로젝트별로 POST /projects/{projectId}/exports에 대해 단일 큐를 사용하세요. 그렇지 않으면 익스포트가 순서 없이 도착할 수 있습니다.

​
다음 단계