comfyui_o1key/docs/decisions/0006-grok-video-api-and-workflow-migration.md

0006: Grok Video API and workflow migration

• Status: Accepted
• Date: 2026-09-05
• Owners: Maintainers

Context

The released O1keyGrokVideo node used the legacy /v1/videos API, retired model names, and a positional widget layout containing a per-node network route. The current O1Key Grok Video API has separate generation, edit, and extension endpoints, new model identifiers, different duration and resolution limits, and one shared task-status endpoint.

ComfyUI stores widget values by position. Replacing the schema without migrating widgets_values would assign old prompts, models, durations, and resolutions to the wrong controls. Renaming the optional reference-image sockets would also make old connections harder to restore reliably.

Decision

• Keep the released O1keyGrokVideo node ID and the existing VIDEO output position.
• Use O1keyGrokVideo for text, image, and multi-reference generation, and O1keyGrokVideoEdit for edit and extension operations.
• Keep API transport, payload validation, polling, and response parsing in clients/grok_video_client.py.
• Validate all user-controlled parameters before temporary uploads or paid generation calls.
• Migrate legacy generation workflows before ComfyUI maps positional widget values:
  • remove the legacy per-node network route through the shared route migration;
  • map grok-imagine-video-1.5-preview to grok-imagine-video-1.5;
  • map grok-imagine-1.0-video to grok-imagine-video;
  • infer multi-reference mode when a legacy reference-image socket is connected, otherwise use text mode;
  • rename 参考图1 through 参考图7 sockets to 图片1 through 图片7;
  • clamp legacy durations above the new API maximum to 15 seconds;
  • append new controls rather than shifting values in workflows already saved with the intermediate schema.
• Never write temporary upload or result URLs to logs or workflows.

Consequences

Existing workflow node IDs and output links remain valid, while old parameter values are converted to the new API contract. A legacy 16- or 20-second selection becomes 15 seconds because the replacement generation API has a hard 1–15 second range.

The frontend migration remains required runtime code as long as pre-migration workflows are supported. Future Grok widget additions must remain append-only or include another idempotent migration and regression test.

Alternatives considered

• Register entirely new node IDs and leave the old node untouched. Rejected because it would strand saved workflows on an obsolete API.
• Reinterpret old widget arrays in backend execution only. Rejected because ComfyUI assigns widget values before execution, so the visible controls and saved values would still be corrupted.
• Preserve retired model names as aliases in the node dropdown. Rejected because those identifiers are not valid for the current endpoints and would allow avoidable failed requests.

Validation

• tests/test_grok_video.py protects payload construction, capability limits, schema defaults, media locators, edit duration preflight, and secret-safe error formatting.
• tests/test_o1key_image_generator_frontend.mjs protects legacy Grok widget and socket migration, including idempotency.
• tests/test_temp_media_uploads.py verifies that temporary upload URLs are returned to callers without being printed.
• tests/run_all.py, compile checks, and the package import smoke test validate the bundled Windows environment.