Sora2 上传角色同步 (Grsai)

Character consistency in video is the hard problem, and Sora2's answer is "characters are assets": you show the model a clip of the person you care about, it extracts a reusable character ID, and every future video generation can reference that ID to keep the same face. This node is the "register a character from footage you already have" step, and it works entirely from a local file path - no API image upload, just a path, two timestamps, and a note.

The flow: it takes a local video file, uploads it to the Grsai API, tells the model "the character is the thing visible between these two timestamps," polls until the extraction finishes, and hands you back a character_id string. The same ID is then wired into whatever Sora2 generation node you use (via remixTargetId on Sora2Generator_Grsai or the async submit nodes).

Inputs:

• video_path - absolute path to the local video. The node strips stray quotes and checks the file exists before it bothers the API.
• start_time / end_time - the slice of the video that contains your character, in seconds (defaults 0 → 3). This is the one you'll actually fiddle with: too tight and you capture a blink, too loose and the model grabs two people.
• 备注 (remark) - optional free-text label. Not cosmetic: it's written into your local character library so you can tell the 20 characters apart later.
• api_key - optional, blank uses the pack-wide Grsai key.

Outputs are character_id (the string to reuse everywhere) and status (a success/error report including your remark and whether the record was saved).

The local-library detail is what makes this worth it: on success the node appends a record - timestamp, remark, ID, source filename - to data/character_library.txt inside the pack folder. So you're not just getting an ID back into the graph; you're building a browsable archive of every character you've ever registered, which is a genuinely useful habit for a character-driven workflow. (There's a sibling node, Sora2FromPidCharacter_Grsai, that does the same extraction from a previously generated video's PID instead of a local file.)

Install is the pack-wide routine:

cd ComfyUI/custom_nodes
git clone https://github.com/jieg9341-lab/ComfyUI-nkxx

Restart (first boot auto-installs requests, pandas, yt-dlp, etc.), and have a Grsai key from nkxx.grsai.ai.

Grounded gotchas:

• The upload happens over HTTPS with a token handshake (/client/resource/newUploadTokenZH) and can take a while for long files - the API timeout for the file POST is 300 seconds. Keep your source clip short; you only need a few seconds for the extraction anyway.
• This node blocks while it polls (up to 15 minutes of polling, same as the sync video generator). It's an output node, so it's meant to sit at the end of a branch; plan for it to hold the queue.
• The character_id is only useful if you actually keep it. Since it's a plain STRING output, route it to a text display or the library file does the remembering for you.
• No character ID means the whole premise collapses, so the node returns an explicit character_id empty + error status rather than silently continuing. Read the status string if something looks off.