NINI
4.2 KiB
사용자와 생성 도구의 전달 형식
사용자는 저장소 루트의 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을 사람이 읽는 요약이다. 공통·단계별 필드 타입은 진행 스키마와 단계 스키마, 시작 형태는 양식에 있다.
단계는 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 사용자 승인과는 별개다.