NINI
36 lines
4.2 KiB
Markdown
36 lines
4.2 KiB
Markdown
# 사용자와 생성 도구의 전달 형식
|
|
|
|
사용자는 저장소 루트의 Codex에서 `$short-video-workflow`와 주제·언어로 새 제작을 요청한다. 개별 `$short-video-<작업>` 호출에는 기존 제작과 사용할 선행 결과를 지정한다. 별도 HTTP 인증·응답 코드는 없고 로컬 JSON·검토 문서가 전달 표면이다. 누락·미확인·실패는 문제 기록과 준비 상태로 반환한다.
|
|
|
|
## 공통 출력
|
|
|
|
진행 기록은 schema_version="1.0", project_id, brief={topic,language}, settings, stages, reviews다. stages의 항목은 {stage_id,status,revision,artifact_path,issues}, issues는 {code,message,blocking}다. reviews의 항목은 {review_id,decision,artifact_refs,feedback}이며 artifact_refs는 {stage_id,revision} 배열이다.
|
|
|
|
단계 출력은 {schema_version,project_id,stage_id,revision,inputs,payload}다. revision은 1부터 시작하고 inputs는 실제 사용한 선행 버전 배열이다. project_id는 유일한 소문자 영숫자·하이픈이고, 경로는 저장소 루트 기준 상대 경로다. 이전 결과는 보존하며 review.md는 같은 JSON을 사람이 읽는 요약이다. 공통·단계별 필드 타입은 [진행 스키마](../contracts/project.schema.json)와 [단계 스키마](../contracts/artifact.schema.json), 시작 형태는 [양식](../templates/)에 있다.
|
|
|
|
단계는 01-topic, 02-research, 03-script, 04-title, 05-tts-split, 06-tts, 07-cuts, 08-scenes, 09-entities, 10-references, 11-images, 12-motion, 13-compose, 14-review다. 상태는 pending/draft/awaiting_input/awaiting_review/complete/stale/failed, 검토는 topic/story/scenes/final, 결정은 pending/approved/changes_requested/stale다.
|
|
|
|
## 외부 결과 제출
|
|
|
|
| 단계 | 요청 | 결과 |
|
|
|---|---|---|
|
|
| 06 | engine, conda_env, language, units | engine, model, voice, files, narration, unit_ranges |
|
|
| 10 | model, style_reference, items | items |
|
|
| 11 | model, frames | frames |
|
|
| 12 | clips | clips |
|
|
| 13 | timeline, narration_path, captions, title | video, captions_path |
|
|
|
|
06 units는 {id,block_ids,display_text,spoken_text,pronunciation_notes}, files는 {unit_id,media}, narration은 media, unit_ranges는 {unit_id,start_ms,end_ms}다. 요청 engine은 Qwen3-TTS, conda_env는 qwen3-tts이며 model·voice는 실제 사용값을 결과에 기록한다.
|
|
|
|
10 요청 items는 {id,kind,entity_id,prompt}, 결과 items는 {reference_id,media}다. kind는 style/character/background이며 스타일만 entity_id=null이다. model은 gpt-image-2.5-sunburst, style_reference는 references/1.png다. 11 요청 frames는 {id,cut_id,position,prompt,reference_ids}, 결과 frames는 {frame_id,media}다. position은 start/end이고 컷마다 둘 다 하나씩 필요하다.
|
|
|
|
12 요청 clips는 {cut_id,start_frame_id,end_frame_id,duration_ms,motion_prompt}, 결과 clips는 {cut_id,media}다. 13 timeline은 {cut_id,video_path,start_ms,end_ms}, captions는 {id,start_ms,end_ms,text} 배열이다. video는 media이고 captions_path는 실제 SRT 경로다. 특정 영상·합성 엔진이나 API 파라미터는 계약에 고정하지 않는다.
|
|
|
|
media는 {path,kind,verified,duration_ms,width,height}다. kind는 audio/image/video, 미확인 값은 null, verified는 불리언이다. 검증된 음성은 WAV·길이·width/height=null, 이미지는 PNG·크기·duration_ms=null, 영상은 MP4·길이·크기가 필요하다. 시간은 ms 정수이며 완료한 길이는 양수다. 결과의 ID는 요청에 존재해야 한다.
|
|
|
|
## 대기와 오류
|
|
|
|
request만 있으면 result=null이고 실제 배정된 외부 단계는 awaiting_input이다. 부분 결과는 보존하되 완료가 아니다. 없는 파일·지원하지 않는 언어·시간 불일치는 issues의 원인·blocking 여부와 돌아갈 단계를 보고한다. 키·인증정보는 이 형식에 포함하지 않는다.
|
|
|
|
14 checks는 {area,verdict,evidence}, findings는 {severity,description,stage_id,cut_id}, recommendation은 pass/revise/incomplete다. area는 story/visual/audio/captions/timing/consistency, verdict는 pass/fail/not_checked, severity는 blocking/minor다. 특정 컷이 아니면 cut_id=null이다. 실제 완성본 부재는 incomplete이며 여섯 영역의 통과와 blocking 없음이 확인되어야 pass를 추천한다. 실제 final 사용자 승인과는 별개다.
|