Geokkk/cephalon-comfyui-video

Cephalon Cloud（端脑云）→ ComfyUI 動画生成 API リンク

完全実行可能スクリプト（本リポジトリ scripts/）：

• lucy_run.py — Workbench 直結 CLI（推奨ルート、インスタンス不要）：微信扫码ログイン → SSO セッション構築 → ゼロ消費見積り → ロック価格送信（冪等キーで重複課金防止）→ ポーリング → sha256 検証ダウンロード → 画像素材アップロード。4テンプレート（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 = パスが存在しない。この3点で調整すること。
• 公開鍵/秘密鍵を逆にしても 401。スクリプトは自動対向リトライを実装済み。
• GET インターフェースのクエリパラメータ：パラメータ名は snake_case（page_index/page_size）だが、ダブルクエリは必ず 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 再確認：効率的な流れ（生成後即クローズ）では作成からクローズまで約 24 分、推定約 14 CEP——節約の鍵：生成完了後すぐに close すること。

孤児インスタンス防止（実績あり、2026-09-28 に約1時間分の CEP を実際に消費）

• 作成成功後、待機ループに入る前に即座に mission_id をディスクに書き込む。待機中にタイムアウト/中断でプロセスが死んでも ID が失われて孤児になることはない。
• create の先頭で state ファイルを確認：既存の waiting/doing/supplying インスタンスがあれば再利用し、新規作成しない。
• submit 前にインスタンス状態を確認、supplying/doing 以外であれば送信を拒否。
• 孤児 ID を失うと、ユーザーが端脑云コンソールで手動停止するしかなくなる（スノーフレーク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ステップ) → 低ノイズモデル+LoRA+KSamplerAdvanced(2→4ステップ) → VAEDecode → CreateVideo(fps 16) → SaveVideo。latent は EmptyHunyuanLatentVideo(480x480x73, batch 1)。テキストエンコーダーは umt5_xxl_fp8_e4m3fn_scaled.safetensors (CLIPLoader type=wan)。
• 4ステップ生成で約 4.5 秒、480x480 16fps 動画（RTX4090 実測）、送信から完了まで約 3-4 分（モデルロード込み）。
• TI2V 5B の公式パラメータは 14B と全く異なる（公式テンプレート video_wan2_2_5B_ti2v.json 実測解析）：単一 KSampler 20 ステップ / cfg 5 / uni_pc / simple + ModelSamplingSD3 shift 8 + CreateVideo fps 24；5B は単一モデルで高低ノイズ UNET の二重構造なし。5B 専用蒸留 LoRA は存在せず、4ステップルートは適用不可。
• 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 ステップサンプリング単一ショット 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 のタイムアウトは 300s 必須（デフォルト 60s の読み取りタイムアウトでは 900KB アップロードに耐えられない）；送信はリトライループ x5（再送信は安全——既にキューイングされていればサーバーが拒否する）；socket.setdefaulttimeout(180) でダウンロードの無限ハングを防止。送信応答が失われた場合は /history をスキャンしてファイル名プレフィックスで生成物を検索する。
• ショット3 の教訓：POST がアップロード段階で中断された後、ワークフローは全くキューイングされていなかった（キュー空 + history に記録なし）。バックグラウンドポーリングが無限に空回りして CEP を消費する——最初に /queue と /history を確認してから再送信すること。
• 20 ステップ 720p 単一ショット約 5-6 分生成 + 1 分アップロード/ダウンロード；8ショット全体（障害による空回り 40 分を含む）で約 2 時間のインスタンスレンタル。
• xfade 連結：段階的に 2 つずつ結合（長い 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 は Web 画面でタイプ値を確認すること（ドキュメントのコメント欄では API のデフォルトはベーシック版と記載）。