# 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.