Geokkk/cephalon-comfyui-video

Cephalon Cloud（端脑云）→ ComfyUI 비디오 생성 API 링크

완전 실행 가능한 스크립트（본 저장소 scripts/）：

• lucy_run.py — Workbench 직접 연결 CLI（권장 경로, 인스턴스 불필요）：微信扫码 로그인 → SSO 세션 생성 → 제로 소모 견적 → 가격 잠금 제출（멱등 키로 중복 차감 방지）→ 폴링 → sha256 검증 다운로드 → 이미지素材 업로드。네 템플릿（t2v/i2v/fl2v/r2v）2026-10-14 모두 실주행 검증 완료.
• cephalon_api.py — user-center HMAC 서명 + 인스턴스（missions）CLI
• cephalon_verify.py — 링크 검증；cephalon_keys.py — 키 템플릿（env 변수 우선)
• run_fairy_pipeline.py / concat_fairy.py — 자체 구축 인스턴스 다중 샷 파이프라인（구버전 경로)

Lucy 워크플로우 링크（lucy-agent 이미지 워크플로우、微信扫码 로그인、video.lucy.run Workbench 견적과 실제 실행）：references/lucy-workflow-api.md 참고.

Workbench 직접 연결 빠른 시작（lucy_run.py）

export CEPHALON_PUBLIC_KEY=<32자리 hex> CEPHALON_PRIVATE_KEY=<64자리 hex>
python scripts/lucy_run.py login                      # 微信扫码，JWT 저장 lucy_state/token.txt
python scripts/lucy_run.py balance                    # 잔액（100 units = 1 CEP）
python scripts/lucy_run.py upload 첫프레임.png         # i2v/fl2v/r2v 필요，asset_id 반환
python scripts/lucy_run.py submit --template t2v --seconds 5 --yes \
  --prompt "…… overall_soundscape: …… non_diegetic_music: None."
python scripts/lucy_run.py download <run_id>

주의사항：가격 100 units/초（5s=5 CEP、10s=10 CEP、15s=15 CEP）；차감은 제출 순간에 이루어지며, running 상태 이후 취소 불가；제출 전 스크립트가 출력하는 견적을 반드시 확인하세요. 파라미터 세부 사항과 함정은 reference 참고.

인증（실측 검증，문서에 함정 있음）

• HMAC-SHA256. 서명 문자열 = JSON( relative_uri + 정규화된 body )，키 = 개인 키（64자리 hex），요청 헤더 Hmac-Key: 공개 키(32자리 hex) + Hmac.
• 핵심 함정：requestURI는 user-center 기본 경로에 대한 상대 경로（예：/v1/load-balance），문서 링크에 표시된 /cephalon/user-center/v1/... 접두사가 아님. 접두사를 포함하면 반드시 401（빈 body 전송 계층 거부，오류 메시지 없음）.
• body 정규화：json.dumps(..., sort_keys=True)，요청 body와 완전히 일치해야 함.
• 401（빈 msg）= HMAC 서명 실패；code 40000 로그인 상태 만료 = 인증 헤더 없음；404 = 경로 없음. 이 세 가지로校准.
• 공개 키/개인 키를 반대로 넣어도 401. 스크립트에 자동 교체 재시도 로직 포함.
• GET 인터페이스의 query 파라미터：파라미터 이름 snake_case 사용（page_index/page_size），단, 두 개 파라미터 query는 반드시 401（서버 측 제한，단일 파라미터는 200）. mission_list에 쿼리 파라미터 포함 시 사용 불가，건너뛰기；직접 create/status/access/close 사용.
• POST/PUT 인터페이스：서명 문자열 = URI + 정규화된 body JSON 문자열（실측 통과）.

API 엔드포인트（base: https://prod.unicorn.org.cn/cephalon/user-center）

• POST /v1/user/missions/batch body: {batch_size, type, gpu_version, gpu_num} → data: [雪花ID]
• GET /v1/user/missions/{id} → 상태/urls（페이지네이션 파라미터 불필요，단일 ID 조회 가능）
• PUT /v1/user/missions/close/batch body: {ids: [...]}
• GET /v1/load-balance（파라미터 없음）→ 사용자 로드 밸런싱 서비스 목록
• GET /v1/load-balance/access-address/{id} → frpc_address/fb_address

인스턴스 생명 주기（과금）

• waiting（무료）→ doing（접수됨, 실행 안 됨）→ supplying（과금 중, RTX4090 실측 unit_cep=36 CEP/시간, 2026-09-29 청구서 확인） → succeed/failed/canceled.
• 준비 시간 일반적으로 5-8분（waiting 약 5분 + doing 약 2분）.
• 생성 후 urls 필드 나타남（["https://wp08.unicorn.org.cn:PORT", ".../fb"]）. URL은 HTTPS + 비표준 포트，자체 서명 인증서（requests/urllib에서 인증서 검증 비활성화 필요）.
• doing 단계에서 urls가 아직 발급되지 않을 수 있음：create 스크립트에서 "접속 주소를 가져오지 못했습니다" 오류와 함께 종료되는 것은 정상적인 타이밍 문제，1-2분 후 create 재실행（스크립트의 고아 방지 로직이 자동으로 인스턴스 재사용 및 base 보완），새 인스턴스를 중복 생성하지 마세요.
• mission status 반환 값에 username/password 필드 포함（인스턴스 Web UI 자격 증명, 예: admin/cephalon），인스턴스 UI 로그인 시 사용；HMAC 키와 무관.
• 사용 후 반드시 close 인터페이스 호출，그렇지 않으면 유휴 상태로 CEP 소모. 종료 후 로컬 cephalon_state.json도 succeed로 업데이트해야 다음에 고아 인스턴스로 오판하지 않음. 단일 작업 청구서 약 2124 단위（≈21.24 CEP）약 1시간 supplying + 모델 로딩/생성 포함；2026-09-30 2차 검증：빠른 흐름（생성 완료 후 즉시 종료）생성부터 종료까지 약 24분，약 14 CEP 추정——비용 절감 핵심：생성 완료 후 즉시 close.

고아 인스턴스 방지（함정 경험，2026-09-28 실제로 약 1시간 CEP 소모）

• 생성 성공 후 mission_id를 즉시 디스크에 저장한 후 대기 루프 진입. 대기 중 timeout/인터럽트로 죽어도 ID를 잃지 않음.
• create 시작 시 state 파일 확인：이미 waiting/doing/supplying 인스턴스가 있으면 재사용，새로 생성하지 않음.
• submit 전 인스턴스 상태 확인，supplying/doing이 아니면 제출 거부.
• 고아 ID를 잃으면 사용자가 Cephalon Cloud 콘솔에서 수동으로 중지해야 함（雪花 ID는 열거 불가）.

ComfyUI API（인스턴스 준비 후）

• POST /prompt body: {"prompt": {API 형식 워크플로우}, "client_id": "..."} → prompt_id
• GET /history/{prompt_id} → status.completed + outputs
• GET /view?filename=...&subfolder=...&type=output → 결과 다운로드
• GET /object_info（11MB）→ 모든 노드 정의；GET /object_info/{NodeName} 단일 노드.
• API 형식：{node_id: {class_type, inputs: {param: value 또는 [from_node, slot]}}}.
• 공식 Wan2.2 템플릿은 새 UI 중첩 서브그래프 형식（definitions.subgraphs），서버에 서브그래프 타입이 등록되지 않으면 오류 발생. 인라인으로 평면 API 형식으로展开 필요. 템플릿 해석：Wan2.2 T2V = 고노이즈 모델(UNETLoader)+lightx2v LoRA+ModelSamplingSD3(shift 5)+KSamplerAdvanced(0→2 step) → 저노이즈 모델+LoRA+KSamplerAdvanced(2→4 step) → VAEDecode → CreateVideo(fps 16) → SaveVideo. latent는 EmptyHunyuanLatentVideo(480x480x73, batch 1) 사용. 텍스트 인코더 umt5_xxl_fp8_e4m3fn_scaled.safetensors (CLIPLoader type=wan).
• 4 step 생성 약 4.5초 480x480 16fps 비디오（RTX4090 실측），제출부터 완료까지 약 3-4분（모델 로딩 포함）.
• TI2V 5B 공식 파라미터는 14B와 완전히 다름（공식 템플릿 video_wan2_2_5B_ti2v.json 실측 해석）：단일 KSampler 20 step / cfg 5 / uni_pc / simple + ModelSamplingSD3 shift 8 + CreateVideo fps 24；5B는 단일 모델로高低噪 UNET 없음. 5B 전용 증류 LoRA 없음，4 step 경로 적용 불가.
• TI2V 5B 해상도는 1280x704 또는 704x1280만 가능（Wan22ImageToVideoLatent 폭 높이 스텝 32，720 높이 불가；공식 「720P」는 실제로 704）. 프레임 길이 제약 (n-1)%4==0.
• 공식 템플릿 기본 121 프레임 = 5초 학습 길이；>121 프레임은 동적 저하 위험，긴 장면은 ≤121 프레임 다중 샷으로 분할.
• I2V：Wan22ImageToVideoLatent의 optional start_image에 IMAGE 연결；첫 프레임은 easy loadImageBase64 사용（base64_data 문자열 입력，multipart 업로드 불필요）.

검증된 모델 라이브러리（3755 노드）

• Wan2.2 전 계열（T2V/I2V 14B fp8、TI2V 5B fp16）、Wan2.1、LTX-2（19B/22B dev/distilled）、LTX-Video 0.9.5、HunyuanVideo 720p、SVD、Mochi、Hunyuan3D-2. TI2V 5B 전용 증류 LoRA 없음（357개 LoRA 중 5b/ti2v 없음），전체 품질 20 step 샘플링 단일 샷 720p 약 5-6분.
• LoRA 357개（wan2.2 lightx2v 4steps v1.1 high/low noise 포함）.
• 탐지 스크립트：object_info.json 다운로드 후 로컬에서 CheckpointLoaderSimple/UNETLoader/VAELoader/CLIPLoader choices + 비디오 노드 존재 여부 분석.

다중 샷 체인 방식 완성 영상（2026-10-01 720p 실측 실행 성공）

• 스크립트：scripts/run_fairy_pipeline.py（create/shot1/shot N/download/close）+ build_ti2v_t2v.py/build_ti2v_i2v.py（워크플로우 생성기）+ concat_fairy.py（xfade 연결）. 사양 파일 shots_spec.json.
• 체인 연속성 보장：샷1 T2V → ffmpeg -sseof -0.15로 마지막 프레임 추출（JPG q2 ~200KB，PNG 사용 금지——900KB는 터널 업로드 중 반드시 중단됨）→ 각 샷은 이전 샷의 마지막 프레임을 start_image로 사용.
• 터널 불안정 세 가지 대책：POST /prompt timeout 반드시 300s（기본 60s 읽기 타임아웃은 900KB 업로드 견디지 못함）；제출 시 재시도 루프 x5（재제출 안전——이미 큐에 있으면 서버에서 거절）；socket.setdefaulttimeout(180)으로 다운로드 무한 대기 방지. 제출 응답 손실 시 /history 스캔하여 파일 이름 접두사로 결과물 탐색.
• 샷3 교훈：POST가 업로드 단계에서 중단되면 워크플로우가 큐에 전혀 들어가지 않음（큐 비어 있음 + history에 기록 없음），백그라운드 폴링이 무한 유휴 상태로 CEP 소모——먼저 /queue와 /history 확인 후 재제출.
• 20 step 720p 단일 샷 약 5-6분 생성 + 1분 업로드/다운로드；8샷 전체（장애 유휴 40분 포함）약 2시간 인스턴스 임대 기간.
• xfade 연결：단계별로 두 개씩 병합（긴 filter_complex 한 번에 하면 디버깅 어려움），offset = 누적 길이 - 0.5s，완성 영상 길이 = Σ단일 샷 - (N-1)×0.5s.

작업 유형 열거（4.1 생성 시 사용）

comfyui_time（기본版）/ sd_time / sd_cmd_time（고급版）/ fooocus_time / sd_xl_time / jp_time / jp_conda_time / tabby_time / ascend_time / wt_time / ssh_time. 프로페셔널版 ComfyUI는 웹 페이지에서 유형 값 확인 필요（문서 댓글에서 API 기본값은 기본版이라고 함）.