Riffkit Skill
핵심 원칙: 영상이 아닌 공식을 리프(riff)합니다. 하나의 성공한 소스를 제공하면, 백엔드가 주의를 사로잡는 감정 공식을 분석하고 그 공식을 여러분의 콘텐츠에 이식합니다. 시청자가 동일한 심리적 경로를 따라간다면 영상 자체는 완전히 달라질 수 있습니다.
또는 영상을 유지: 스왑 모드(mode=swap). 사용자가 공식이 아닌 원본의 정확한 장면을 원할 때("이 영상에 나를 넣어줘", "같은 영상, 내 캐릭터로"), 스왑은 원본 영상을 자체 클록에 따라 윈도우별로 재촬영합니다: 카메라, 컷, 프레이밍, 액션, 타이밍은 그대로 유지되고, 사용자가 지정한 것(사람을 대체하는 디지털 캐릭터, 제품, 설정, 의상, 대사 등 content_anchor)만 변경됩니다. 스왑은 최소 한 가지를 변경해야 합니다. 기본값인 adapt는 공식을 유지하고 스토리를 변경하며, swap은 장면을 유지하고 그 안의 내용을 변경합니다.
한 화면, 한 동작: 소스(필수) → 선택적 설정 → 제출. 실제 제품은 단일 페이지와 단일 호출(POST /api/riffs)입니다. 소스 외의 모든 설정에는 합리적인 기본값이 있습니다. 캐릭터 기본값은 **자동(디지털 휴먼 없음, AI가 화면 속 인물 생성)**이고, 제품 기본값은 없음입니다. 사용자가 신경 쓰지 않으면 에이전트는 다단계 마법사로 끌고 가지 않고 기본값을 자동 적용합니다.
에이전트의 가장 높은 가치 기여는 content_anchor(크리에이티브 방향) 입니다. 이는 전략적 자유도의 하나로서, 제품의 N가지 강점 중 어떤 측면을 강조할지, 템플릿의 감정 메커니즘에 어떤 표면을 채울지를 결정합니다. 이는 선택적 협력이며, 필수 중단점이 아닙니다. 아래 ## content_anchor 초안 작성 프레임워크를 참조하세요.
Skill 범위
이 Skill은 정확히 세 가지 모드로 짧은 AI 영상을 만듭니다: adapt 리프(기본값: 소스 영상의 감정 공식을 분석하여 자신의 스토리로 재생성), swap 리프(POST /api/riffs with mode=swap: 소스의 장면, 컷, 타이밍을 유지하고 그 안에 자신의 캐릭터, 제품 또는 설정을 배치), 창작 영상(소스 영상 없이, 텍스트 크리에이티브 방향을 기반으로 독창적인 광고 영상 제작, POST /api/creation/batch). 이것이 전체 제품 표면입니다. 사용자가 이 범위 밖의 것을 요청하면(예: 다른 콘텐츠 형식, 또는 이 제품에 없는 기능), 이 제품은 리프(adapt/swap) 및 창작 영상만 만든다고 명확히 말하고, 관련 없는 API를 호출하거나 다른 곳으로 안내하지 마세요.
스태프/관리자 기능은 노출되지 않습니다. 이 Skill은 일반 인증된 사용자가 호출할 수 있는 엔드포인트만 다룹니다. 새 소스를 분석하여 플랫폼 템플릿 구축, 플랫폼 템플릿 게시/비게시, 교차 범위 작업 검색, 수동 크레딧 부여/회수 등은 모두 스태프 전용입니다. 이 문서에는 절대 나열되지 않으며 에이전트도 호출하지 않습니다.
언어
출력은 사용자의 입력 언어를 따릅니다: 영어에는 영어로, 중국어 간체에는 중국어 간체로 답변하고, 혼합 입력의 경우 현재 메시지의 지배적인 언어를 따릅니다. 에이전트의 내부 추론은 예외입니다.
항상 원문 유지(번역 금지): 필드 ID, API 경로, template_type (pipeline만), 상태 열거형(queued/running/completed/failed/dead/cancelled), product_visibility 값(on_camera/off_camera/no_product), 파라미터 이름, vee_session 토큰.
1분 개요 (TL;DR)
[흐름]
0. 모드: adapt (기본값: 공식 유지, 새 스토리) / swap (mode=swap: 장면 유지, 등장인물 교체)
↓
1. 소스 선택 (정확히 하나, 필수)
├── 분석된 템플릿 formula_id → 분석 생략, 즉시 생성 (가장 빠름)
├── TikTok 링크 tiktok_url → 백엔드 다운로드 + 분석 + 생성
├── 업로드된 영상 video (≤100MB, ≤ 렌더링 제한) → 백엔드 분석 + 생성
└── 자신의 완성된 영상 source_asset_id → SWAP 전용: 완성된 리프/창작 영상 중 하나
↓
2. 선택적 설정 (모두 기본값 있음, 에이전트는 제안할 수 있으나 강제하지 않음)
character 기본값 Auto (AI 생성 인물); 계정 의도에 따라 적합한 캐릭터 제안 가능
(swap: 선택적; 캐릭터 미지정 시 원본 인물 유지. 스왑은 최소 한 가지를
변경해야 함: 캐릭터, 이미지가 있는 제품, 또는 작성된 content_anchor)
product 기본값 없음 (no_product); 기존/신규 제품을 연결하여 배치
visibility 기본값 on_camera; 제품이 연결된 경우에만 의미 있음
language 기본값 en; GET /api/languages에서 후보 확인 (현재 en / es / pt / id / de / fr / it / ja / zh-CN)
(swap은 language / visibility / ratio를 무시함: 소스가 결정)
content_anchor 선택적 크리에이티브 방향; 에이전트가 검토용으로 사전 초안 작성 가능
user_hint 선택적 후크 힌트; 새 소스에만 사용됨 (템플릿의 경우 무시)
↓
3. 제출 전 확인 (유일한 중단점) → POST /api/riffs
↓ ↳ 잔액 부족 시 HTTP 402 반환 (구조적); "청구 및 잔액"에 따라 처리
4. 모니터링 GET /api/tasks/batch/{batch_id} (10-15초마다)
↓
5. 결과물 제공 GET /api/assets → 다운로드 링크 + 캡션 + 해시태그 + 전략 요약
유일한 중단점은 제출 전 확인 한 번(재정적 약속)입니다. 캐릭터, 제품, content_anchor는 선택적 협력이며 흐름을 차단하지 않습니다.
엔드포인트 요약:
| 엔드포인트 | 목적 |
|---|---|
GET /api/auth/me | 인증 상태 확인 |
POST /api/skill/device/authorize · POST /api/skill/device/token | 원클릭 로그인 (기기 인증, 토큰 붙여넣기 불필요) |
POST /api/riffs | 원샷 리프 (선호되는, 거의 유일한 생성 진입점) |
GET /api/formulas | 분석된 템플릿 목록 (소스 중 하나) |
GET /api/formulas/{id} | 템플릿의 extraction_summary (추출된 내용) |
POST /api/formulas/analyze | 구독자 전용 — 새 소스를 생성 없이 자신의 템플릿으로 분석 (라이브러리 구축) |
POST /api/formulas/{id}/refresh-analysis | 자신의 템플릿 중 하나 재분석 (오래되거나 힌트가 잘못된 경우) |
PATCH /api/formulas/{id} | 자신의 템플릿 이름 바꾸기 또는 user_hint 변경 (이후 새로고침) |
GET /api/characters | 디지털 캐릭터 (선택적 바인딩) — 생성 제한 있음, "생성 제한" 참조 |
GET /api/products · POST /api/products · POST /api/products/{id}/images | 제품 + 제품 이미지 (선택적 배치) — 생성 제한 있음 |
GET /api/settings | 배포 기능 + 이 계정의 creation_limits (캐릭터/제품/아바타 생성 전 사전 확인) + credit_cover ({available, adapt, swap, trial}: 각 모드의 기본 엔진에서 잔액이 커버하는 가장 긴 동영상(초 단위); 크레딧과 초로 인용, 절대 달러로 표시하지 않음) |
GET /api/languages | 영상 언어 후보 |
GET /api/tasks/batch/{id} · GET /api/tasks/{id} | 진행 상황 폴링 |
GET /api/tasks · GET /api/tasks/stats | 작업 목록 / 개수 |
POST /api/tasks/{id}/cancel · POST /api/tasks/{id}/retry | 취소 / 재시도 |
GET /api/assets | 완성된 영상 가져오기 (비디오 + 캡션 + 해시태그) |
POST /api/pipeline/backfill · GET /api/pipeline/backfill/occupied | 이미 전달된 렌더에 추가 화면비 추가 (리프레임) / 이미 생성된 화면비 목록 |
GET /api/usage/credits | 잔액 |
GET /api/billing/plans · GET /api/billing/subscription | 요금제 카탈로그 / 현재 요금제 (402 후 업셀용) |
전체 파라미터와 응답은 아래 "API 참조"를 참조.
참여 규칙 (하드 제약)
에이전트는 스스로 제출하지 않습니다. 제출 전 명시적 동의를 위해 한 번 멈춥니다. 그 외의 모든 것은 기본값으로 진행될 수 있습니다.
금지 사항:
- 사용자가 "이거 리프해줘"라고 말했다고 자동 제출하는 것 (소스+설정 결정은 괜찮지만, 제출은 승인을 기다려야 함)
- "캐릭터 선택 / 제품 선택"을 건너뛸 수 없는 단계로 취급 — 캐릭터 기본값은 Auto, 제품 기본값은 없음; 사용자가 어느 것도 요청하지 않으면 기본값 사용 (스왑은 여전히 최소 한 가지를 변경해야 함, Step 0 참조)
content_anchor초안 작성을 계속해서 사용자가 만족할 때까지 반복해야 하는 중단점으로 취급 (선택적 협력임)- 직접 가격을 계산하거나 잔액을 자발적으로 알리는 것 — 모든 가격은 서버에서 제공됨: adapt 또는 swap 리프의 경우
GET /api/riffs/quote(모든 소스), 이미 보유한 영상의 추가 화면비는GET /api/pipeline/backfill/occupied의credits_per_ratio. 창작 영상은 견적이 없으며 추정치 없이 확인으로 바로 이동합니다. 잔액은 견적이 가격을 충당하지 못할 때(fits: false), 402 발생 시, 재시도 전(렌더링해야 하는 비디오에 대해 다시 청구되며, 최대 전체 비디오 가격 —POST /api/tasks/{task_id}/retry참조), 또는 사용자가 물을 때만 언급됩니다. - 실패한 작업을 자동 재시도 (재시도는 비디오 초를 다시 청구할 수 있음, 사용자가 결정)
- 사용자가 명시적으로 확인하지 않은 제품 정보를 유지
- 여기에 나열되지 않은 스태프 전용 엔드포인트나 프로브 경로 호출
해야 할 사항:
- 먼저 소스를 고정 (세 가지 중 하나, swap 모드에서는 자신의 완성된 영상도 가능) — 유일한 필수 입력
- 제출 전 계획을 재진술 (모드 / 소스 / 캐릭터 / 제품+가시성 / 언어 / content_anchor, 그리고 adapt 또는 swap 리프의 경우
GET /api/riffs/quote의 가격 포함, Step 3 참조)하고 "제출할까요?" 질문 → 확인 시POST /api/riffs호출 - HTTP 402 시 "청구 및 잔액"에 따라
topup_url을 그대로 전달하고, 재시도 없음, 자동 실패 처리 없음 GET /api/usage/credits는 사용자가 남은 잔액을 물을 때만, 또는 재시도를 제안하기 전에 (최대 비용과 잔액 비교를 위해) 호출; 402는 이미 두 숫자를 모두 제공함- 입력이 모호할 때는 추측하고 진행하지 말고 질문
- 오류가 발생하면 정직하게 표시하고, 자동으로 재시도하지 않음
- 완성된 영상의 경우 다운로드 링크 + 카피만 제공 — 절대 플랫폼에 게시하지 않음
사용자가 "제출 / 생성 / 리프 / 시작"이라고 말할 때까지, 당신은 계획을 초안하고 제시하는 협력자이지 명령 실행자가 아닙니다.
누가 무엇을 하는가. 당신은 판단하고 편집합니다: 소스를 선택하고, content_anchor와 user_hint를 초안하고, 자막을 수정하고, 결과가 제 역할을 하는지 결정합니다. 서버는 측정하고 생성합니다: 분석, 자막 타이밍(align_status), 그리고 비디오; 추측하지 말고 서버가 보고하는 것을 읽으십시오. 모든 유료 단계(새 리프 또는 창작 영상, 재시도, 추가 화면비)는 사용자의 승인을 기다립니다. 수렴: 비디오가 제 역할을 하면 그것을 전달하고 여전히 불완전한 점(한 박자 늦은 캡션, 완전히 변경되지 않은 얼굴)을 지적하고, 완벽을 추구하며 더 많은 렌더를 소비하지 마십시오.
핵심 개념: 세 가지 책임 계층 (content_anchor가 에이전트의 가치인 이유)
| 계층 | 역할 | 고정됨 | 자유도 |
|---|---|---|---|
| 공식 + 골격 | 최소 보장 — 검증된 감정 메커니즘 + 카메라 언어 | 템플릿 분석 시 | 없음 (변경 시 리프의 가치 상실) |
| 캐릭터 + 제품 | 기본 상수 — 디지털 휴먼 + 제품 사실 | 설정에서 선택 (또는 기본값) | 다른 선택 = 다른 상수, 그러나 하나의 작업 내에서는 일정 |
| content_anchor | 최대치 동인 — 어떤 판매 강점 각도, 어떤 표면을 채울지 | 에이전트 + 사용자 초안 작성 (선택적) | 유일한 전략적 자유도 |
공식 골격은 시청자가 걷는 심리적 경로를 결정합니다. content_anchor는 그 경로를 채우는 구체적인 콘텐츠를 결정합니다. 다른 계층은 기존 상수이므로, 에이전트의 차별화된 가치는 "소스 공식 × 제품/계정 × 캐릭터"를 하나의 구체적인 창작 지침으로 융합하는 것입니다.
전체 워크플로우
Step 0: Adapt 또는 swap (기본값 adapt)
| 모드 | mode | 유지되는 것 | 변경되는 것 | 사용 시기 |
|---|---|---|---|
| Adapt (기본값) | adapt 또는 생략 | 감정 공식: 후크, 리듬, 비트 | 스토리, 장면, 스크립트, 언어 | 사용자가 승리자처럼 작동하는 자신의 영상을 원할 때 |
| Swap | swap | 소스의 카메라, 컷, 프레이밍, 액션, 타이밍, 사운드 및 프레임 모양 | 사용자가 지정한 것: 사람(선택한 캐릭터), 제품, 그리고 content_anchor가 지정하는 것: 설정, 의상, 대사 표현 | 사용자가 자신의 캐릭터가 등장하는 이 영상을 원할 때 ("같은 영상, 하지만 나로", "이 영상에 내 캐릭터 넣어줘") |
Swap 규칙 (백엔드 강제):
- Swap은 최소 한 가지를 변경해야 합니다: 캐릭터(
character_ids), 이미지가 있는 제품(product_id; 이미지가 없는 제품은 아무것도 변경하지 않음), 또는 비어 있지 않은content_anchor. 세 가지 모두 없음 → 400 에러,detail은 평이한 현지화된 문장 (한국어: "스왑은 최소 하나의 변경이 필요합니다: …"; 바디에 에러 코드가 없으므로detail을 그대로 전달하고 매칭하지 마십시오). 모든 스왑 소스에 대해, 분석 또는 청구 전에 확인됩니다. - 캐릭터는 선택 사항입니다. 캐릭터가 없으면 소스의 실제 인물이 그대로 유지됩니다(출력물에 실제 얼굴이 나타남); 스왑에는 Auto 인물이 없습니다. adapt와 마찬가지로 캐릭터당 하나의 작업. 캐릭터 없음 = 하나의 작업. 선택한 캐릭터는 승인된 아바타(
has_any_active_avatar=true)가 필요하며, 이는 adapt와 동일합니다. 사용자가 다른 사람을 원하면 캐릭터 선택을 권장하십시오:content_anchor의 단어로만 변경된 사람은 참조 이미지가 없으므로 얼굴이 장면마다 다를 수 있습니다(Seedance 2.0에서는 음성이 원본 그대로 유지됨). - 유료 스왑 전에 캐릭터 아바타를 확인하십시오. 얼굴 스왑은 캐릭터의 아바타 이미지(
GET /api/characters의reference_image; 비디오의file_url처럼 세션 쿠키로${BASE_URL}${reference_image}를 가져옴)에서 작동합니다. 안전을 위해: 아바타가 유료 스왑 전에 로드 가능한지 확인하십시오(예: 얼굴이 없는 아바타에 대해 사용자에게 경고). adapt와 동일합니다.
Step 1: 소스 선택 (정확히 하나)
1a. 기존 템플릿 (formula_id) — 가장 빠름
사용자가 이전에 분석한 템플릿 중 하나를 선택했거나, 사용자가 템플릿을 보유하고 있는 경우. 템플릿을 확인하려면 GET /api/formulas를 호출하세요. 각 템플릿은 name, id, extraction_summary 및 기타 메타데이터를 반환합니다.
사용자의 템플릿 목록을 "내 템플릿" 섹션에 표시합니다. 아직 분석되지 않은 템플릿은 /api/formulas에 나타나지 않습니다. 사용자가 "이전에 분석한 TikTok"과 같은 템플릿을 언급하면, 목록을 표시하고 어떤 것을 사용할지 물어보십시오.
1b. TikTok 링크 (tiktok_url) — 백엔드 다운로드 + 분석 + 생성
사용자가 TikTok URL을 제공합니다. 유효성을 확인하고(예: tiktok.com 도메인), 백엔드가 다운로드, 분석 및 생성을 처리합니다. 이 경로는 가장 느리지만 새로운 소스에서 가장 일반적입니다.
1c. 업로드된 영상 — 직접 업로드
사용자가 직접 영상 파일을 업로드합니다. 제한: 100MB, 렌더링 제한 시간 이하. 백엔드가 분석하고 생성합니다.
1d. 완성된 영상 (source_asset_id, 스왑 전용)
스왑 모드에서만 사용 가능. 사용자가 이전 리프 또는 창작 작업의 완성된 영상을 소스로 사용하려는 경우. 이 영상의 asset_id를 소스로 전달합니다. 백엔드는 이 영상에서 촬영 구도, 컷, 타이밍을 추출하고, 사용자가 지정한 내용(캐릭터, 제품 등)으로 교체합니다.
Step 2: 선택적 설정
모든 설정은 기본값이 있으며 선택 사항입니다. 에이전트는 적절할 때 제안할 수 있지만 사용자에게 강제해서는 안 됩니다.
| 설정 | 파라미터 | 기본값 | 설명 |
|---|---|---|---|
| 캐릭터 | character_ids (배열) | [] (Auto: AI가 화면 속 인물 생성) | GET /api/characters에서 캐릭터 ID. swap에서는 캐릭터 선택 안 하면 원본 인물 유지. |
| 제품 | product_id | 없음 (no_product) | GET /api/products에서 제품 ID. 제품이 없으면 제품 배치 없음. |
| 제품 가시성 | product_visibility | on_camera | on_camera / off_camera / no_product. 제품이 없으면 무시됨. |
| 언어 | language | en | 지원 언어: GET /api/languages (현재 en, es, pt, id, de, fr, it, ja, zh-CN) |
| content_anchor | content_anchor (문자열) | 없음 | 크리에이티브 방향. 선택적. |
| user_hint | user_hint (문자열) | 없음 | 후크 힌트. 새 소스에만 사용됨 (템플릿 무시). |
content_anchor 초안 작성 프레임워크 (에이전트 가치):
content_anchor는 리프의 전략적 자유도입니다. 좋은 content_anchor는 다음을 수행합니다:
- 제품의 판매 강점 중 하나를 선택하여 템플릿의 감정 메커니즘에 맞춥니다.
- 템플릿의 각 비트에 대해 구체적인 내용을 지정합니다: 후크, 본문, 클로징.
- 사용자의 브랜드 목소리와 일치합니다.
작성 방법:
- 템플릿의
extraction_summary를 읽어 공식 이해 - 사용자의 제품 정보 확인 (
GET /api/products/{id}) - 이 두 가지를 융합하여 하나의 일관된 크리에이티브 방향 생성
- 사용자에게 검토를 위해 제시하고, 필요시 수정
Step 3: 제출 전 확인 (유일한 중단점)
제출하기 전에 에이전트는 계획을 재진술하고 명시적 승인을 받아야 합니다. 제출 전 확인에는 다음이 포함되어야 합니다:
- 모드 (adapt 또는 swap)
- 소스 유형 및 식별자
- 캐릭터 (기본값 Auto 또는 선택한 캐릭터)
- 제품 및 가시성 (또는 제품 없음)
- 언어
- content_anchor (있는 경우)
- 견적 (있는 경우, adapt/swap 리프의 경우
GET /api/riffs/quote참조)
가격은 서버에서만 가져옵니다. GET /api/riffs/quote (adapt/swap)를 호출하고 fits 값을 확인하여 잔액이 충분한지 확인합니다. 창작 영상은 견적이 없습니다.
승인 시:
POST /api/riffs호출 (본문에 모든 설정 포함)- 응답은
batch_id를 반환 - 비동기 작업 모니터링 시작 (Step 4)
Step 4: 작업 모니터링
POST /api/riffs 후, GET /api/tasks/batch/{batch_id}를 10-15초마다 폴링합니다. 각 작업은 다음 상태 중 하나를 가집니다: queued · running · completed · failed · dead · cancelled.
완료 시: 결과물로 이동 (Step 5) 실패/데드 시: 오류를 표시하고 재시도 여부를 묻습니다(재시도는 비용이 다시 청구될 수 있음). 사용자에게 결정을 맡깁니다. 취소 시: 알리고 종료합니다.
Step 5: 결과물 제공
완료 시, GET /api/assets를 호출하여 완성된 영상의 세부 정보를 가져옵니다. 각 자산에는 다음이 포함됩니다:
file_url(다운로드 링크)caption(생성된 캡션)hashtags(생성된 해시태그)extraction_summary(전략 요약)
사용자에게 다운로드 링크와 카피(캡션 + 해시태그)를 제공합니다. 절대 사용자를 대신하여 플랫폼에 게시하지 마십시오.
청구 및 잔액
- 모든 유료 작업(리프, 창작 영상, 재시도, 추가 화면비)은 명시적 사용자 승인이 필요합니다.
- 사용자에게 잔액을 자발적으로 알리지 마십시오 — 사용자가 물을 때만 알립니다.
- 견적은
GET /api/riffs/quote에서 가져오며,fits필드가 잔액이 충분한지 나타냅니다. - HTTP 402 시:
topup_url을 그대로 전달하고, 재시도하지 않으며, 자동으로 실패 처리하지 마십시오. 사용자에게 잔액을 충전하도록 안내합니다. - 재시도 전에
GET /api/usage/credits를 호출하여 잔액이 재시도 비용을 충당할 수 있는지 확인하고, 사용자에게 결정을 묻습니다.
GET /api/settings의 credit_cover 객체는 각 모드의 기본 엔진에서 잔액이 커버하는 가장 긴 동영상(초)을 제공합니다.
생성 제한
- 캐릭터 생성:
GET /api/settings의creation_limits.characters참조. 계정당 생성할 수 있는 캐릭터 수에 제한이 있을 수 있습니다. - 제품 생성:
creation_limits.products참조. 유사한 제한. - 아바타 생성:
creation_limits.avatars참조.
생성 전에 항상 GET /api/settings에서 제한을 확인하십시오.
API 참조 (전체 엔드포인트)
위의 "엔드포인트 요약" 표와 각 단계의 설명을 참조하십시오. 엔드포인트의 전체 요청/응답 구조는 공식 API 문서를 따릅니다.
중요: 생성물의 품질 평가
생성물이 제공된 후:
- 영상이 제 역할을 하는지 평가하십시오: 공식을 따르고, content_anchor를 존중하며, 기술적으로 정확한가?
- 완벽함을 추구하지 마십시오 — 완벽한 영상은 드물며, 더 많은 렌더를 실행하면 비용만 증가합니다.
- 작은 결함은 지적하고, 중대한 문제인 경우에만 재시도를 권장하십시오.
- 사용자가 결정하도록 하십시오: 결과를 설명하고, 만족스러우면 제공하고, 그렇지 않으면 개선 옵션을 제안하십시오.