codegen: expose instant video creation and status commands

[terencecho]

Description

Expose Instant Video through heygen model videos create -d '<JSON>' and heygen model videos get <video-id>. Add examples for text, image, and reference generation, including safe retries with --idempotency-key.

Regenerate the CLI from the companion experiment-framework public spec, commit cd0e2c49c0588a80f384a4bbf50f63fcb876c697. The generated refresh also picks up current public API changes already present in that spec. Add the two folder examples required for strict generation of that current contract.

Merge and release after the API spec companion is deployed. The Instant Video route itself is already present in production; publishing its contract and MCP tools requires the companion deployment.

Testing

• make generate STRICT=1 SPEC=<companion-spec> passed with no missing examples.
• go test ./... passed with the ambient HEYGEN_API_KEY unset; all HTTP tests use local test servers.
• New tests verify all three modes reach POST /v3/models/videos, preserve API-key and idempotency headers, return the accepted video ID, and poll the model-video status route.
• go vet ./... and git diff --check passed.
• No paid generation or CLI release performed.

[github-actions]

Command surface: 4 existing command(s) changed

Changed — these already existed, so a change can break existing calls.

heygen model audio tts create

+ 			Name: "pitch-shift",
+ 			Type: "float64",
+ 			Default: "",
+ 			Required: false,
+ 			Enum: nil,
+ 			Min: nil,
+ 			Max: nil,
+ 			Source: "body",
+ 			JSONName: "pitch_shift",
+ 			Name: "pitch-variance",
+ 			Type: "float64",
+ 			Default: "",
+ 			Required: false,
+ 			Enum: nil,
+ 			Min: nil,
+ 			Max: nil,
+ 			Source: "body",
+ 			JSONName: "pitch_variance",
+ 			Name: "speed",
+ 			Type: "float64",
+ 			Default: "",
+ 			Required: false,
+ 			Enum: nil,
+ 			Min: nil,
+ 			Max: nil,
+ 			Source: "body",
+ 			JSONName: "speed",

heygen video-agent create

+ 			Name: "members",
+ 			Type: "string-slice",
+ 			Default: "",
+ 			Required: false,
+ 			Enum: nil,
+ 			Min: nil,
+ 			Max: nil,
+ 			Source: "body",
+ 			JSONName: "members",
- 			Default: "team",
---
+ 			Default: "space",
- 			Enum: []string{"private", "team", "public"},
---
+ 			Enum: []string{"private", "space", "selected"},

heygen video-agent send

+ 			Name: "idempotency-key",
+ 			Type: "string",
+ 			Default: "",
+ 			Required: false,
+ 			Enum: nil,
+ 			Min: nil,
+ 			Max: nil,
+ 			Source: "header",
+ 			JSONName: "Idempotency-Key",
- 			Required: true,
---
+ 			Required: false,

heygen voice speech create

+ 			Name: "engine",
+ 			Type: "string",
+ 			Default: "",
+ 			Required: false,
+ 			Enum: []string{"starfish", "orca", "elevenlabs", "elevenlabs_v3"},
+ 			Min: nil,
+ 			Max: nil,
+ 			Source: "body",
+ 			JSONName: "engine",

New commands — additive, nothing existing can break.

• heygen folder create
• heygen folder get
• heygen model videos create
• heygen model videos get

_{Reference only, never blocking. See RELEASE.md "Checking for Regressions" for how to read this.}

[jrusso1020]

Review at fad90016d92b912dac19aefe050b4b5e1195c223.

Verdict: APPROVE. Hold the merge until experiment-framework#54249 is deployed, as the body says. That PR has a changes request for a test fixture, and the fixture doesn't touch the spec, so this regen stays valid.

• The regen matches the stated spec commit exactly. make generate STRICT=1 SPEC=<EF cd0e2c49:openapi/external-api.json> on this head leaves gen/ byte-identical: git status is clean, and strict mode found no missing examples.

• The Instant Video part is only model.go and registry.go. Regenerating from #54249's base spec (1492b5f3) differs from this head only by the ModelVideosCreate/ModelVideosGet specs (47 lines) and their two registry lines.

  • videos create is POST /v3/models/videos with --idempotency-key.
  • videos get is GET /v3/models/videos/{video_id}.

• Unrelated churn, flagged. It all comes from the current public spec, not this feature:

  • a new folder group (folder create → POST /v3/folders, folder get → GET /v3/folders/{folder_id});
  • speech flags --pitch-shift, --pitch-variance and --speed, plus --engine;
  • video-agent --members and --idempotency-key, and the message command's summary changes from "Send Message or Request Revision" to "Send Video Agent Message";
  • description-only edits in lipsync, template, video and video-translate.

  All of this is already on EF master behind #54249's base, so deploying #54249 also deploys these endpoints, and releasing after that deploy is safe for them too. The release notes should mention the new folder commands.

• Checks: go test ./... with HEYGEN_API_KEY unset passes, and so does go vet ./.... The new instant_video_test.go covers all three modes, the API-key and idempotency headers, and status polling. CI is all green.

— Rames