Add MiniMax official Token Plan video provider (direct API, not FAL)

[yiyabo]

Implements Part 1 of issue #216: a first-class MiniMax Token Plan video provider that calls the official MiniMax API directly, distinct from the FAL-backed minimax_video.

What this adds

A new tool minimax_tokenplan_video (tools/video/minimax_tokenplan_video.py) that routes through the official MiniMax API (api.minimaxi.com / api.minimax.io) using MINIMAX_API_KEY, so users with a Token Plan subscription consume their own quota instead of FAL credits.

API flow: POST /v1/video_generation → poll GET /v1/query/video_generation → GET /v1/files/retrieve → download.

Why it's a separate tool (not a modification of minimax_video)

The core point of #216 is cost-route transparency. minimax_video routes through FAL_KEY; minimax_tokenplan_video routes through MINIMAX_API_KEY. Both share provider="minimax" but have different tool names, making the cost route explicit in the registry and decision trail.

Features

• Text-to-video and image-to-video (MiniMax-Hailuo-2.3 / MiniMax-Hailuo-2.3-Fast)
• MiniMax-Hailuo-2.3-Fast correctly rejected for text-to-video (the API does not support it)
• Watermark control via aigc_watermark parameter
• Prompt optimizer toggle
• CN endpoint (api.minimaxi.com) by default; global (api.minimax.io) via MINIMAX_REGION=global
• Full error handling with MiniMax base_resp status codes (1002 rate limit, 1004 auth, 1008 insufficient balance, 1026 sensitive content, etc.)
• API key redaction in error messages

Idempotency

All output-affecting fields are in idempotency_key_fields (prompt, model, operation, duration, resolution, first_frame_image, prompt_optimizer, fast_pretreatment, aigc_watermark). Execution-only fields (output_path, poll_interval_seconds, timeout_seconds) are correctly excluded. Lesson applied from PR #240 review.

Scope note

Issue #216 asks for three things:

1. ✅ Official MiniMax Token Plan provider — this PR
2. ⬜ Creator-facing provider readiness report (make doctor enhancement) — broader scope, overlaps with Out-of-box animated-explainer run: Remotion URI bug, unenforced checkpoints, and silent text-card downgrade #210 and Google service-account auth is advertised but non-functional (TTS + Imagen) + false-availability bugs #131
3. ⬜ Fallback/downgrade severity visibility — broader scope, overlaps with Out-of-box animated-explainer run: Remotion URI bug, unenforced checkpoints, and silent text-card downgrade #210

Parts 2 and 3 are left for separate PRs to keep this one focused and reviewable.

Files

File	Description
tools/video/minimax_tokenplan_video.py	New tool (BaseTool subclass, submit/poll/download)
tests/contracts/test_minimax_tokenplan_video.py	49 contract tests (no API key needed)
.env.example	MINIMAX_API_KEY entry
docs/PROVIDERS.md	MiniMax Token Plan provider section

Test results

python -m pytest tests/contracts/test_minimax_tokenplan_video.py -q  # 49 passed
python -m py_compile tools/video/minimax_tokenplan_video.py tests/contracts/test_minimax_tokenplan_video.py  # OK
Full contract suite: 525 passed, 6 skipped

Closes #216 (Part 1).

[Copilot]

Pull request overview

Adds a new first-class MiniMax “Token Plan” video provider tool that calls the official MiniMax API directly (CN/global endpoints) so the cost route is explicit and distinct from the existing FAL-backed minimax_video.

Changes:

• Introduces minimax_tokenplan_video (submit → poll → retrieve → download) using MINIMAX_API_KEY/MINIMAX_TOKEN_PLAN_API_KEY and MINIMAX_REGION.
• Adds contract tests covering BaseTool compliance, idempotency keys, and key status behavior.
• Updates provider documentation and .env.example to expose setup for the new provider.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
tools/video/minimax_tokenplan_video.py	New MiniMax Token Plan provider tool (official API flow, polling, download, output probing).
tests/contracts/test_minimax_tokenplan_video.py	Contract + tool-specific tests ensuring registry discovery, idempotency, and schema behavior.
docs/PROVIDERS.md	Documents the new MiniMax Token Plan provider and setup.
.env.example	Adds MINIMAX_API_KEY (and should reflect the supported alias env var).

[calesthio]

Thanks for the focused provider PR. I reviewed this against docs/PR_REVIEW_GUIDE.md, including Copilot's earlier comments and the latest force-pushed head. The provider direction is useful and aligned with issue #216, and the PR's focused test file passes locally, but a few contract/setup blockers remain.

Findings:

1. The Token Plan key alias is still lower priority than the generic key. _api_key() currently returns MINIMAX_API_KEY before MINIMAX_TOKEN_PLAN_API_KEY. For this tool, the route is the product: if a user has both a generic MiniMax API key and a Token Plan subscription key configured, this provider should not silently choose the generic key. Please either prefer MINIMAX_TOKEN_PLAN_API_KEY first, or remove the alias entirely and make MINIMAX_API_KEY the only supported contract. Given the PR already advertises Token Plan behavior and tests the alias, preferring the Token Plan key is the cleaner fix.

2. The alias is still not reflected in setup-facing docs/errors. .env.example, docs/PROVIDERS.md, install_instructions, and the missing-key error mention only MINIMAX_API_KEY, while the implementation and tests support MINIMAX_TOKEN_PLAN_API_KEY. That leaves a hidden supported config path and makes setup/debug output misleading. Please align docs and runtime messages with whichever env-var contract you choose.

3. callback_url is still an undocumented public input. _build_payload() accepts and forwards callback_url, but input_schema does not declare it. Tool schemas feed registry/docs/agent planning, so accepted provider inputs need to be part of the contract or removed from the implementation.

4. _safe_error() still has the empty-string replacement bug and does not redact the token-plan alias. I reproduced this on the current PR head:

safe-empty: [redacted]a[redacted]b[redacted]c[redacted]
safe-token: [redacted]b[redacted]a[redacted]d[redacted] [redacted]t[redacted]o[redacted]k[redacted]e[redacted]n[redacted]-[redacted]s[redacted]e[redacted]c[redacted]r[redacted]e[redacted]t[redacted]

This happens because os.environ.get("MINIMAX_API_KEY", "") can be empty, and the function never checks MINIMAX_TOKEN_PLAN_API_KEY. Please redact only non-empty configured secret values, including both supported env vars.

Copilot's /v1/files/retrieve error-handling comment does appear addressed: the current code uses _json_or_raise() and _check_base_resp() after retrieving the file metadata. The remaining comments above are still valid on the latest head.

Validation run locally:

• python -m py_compile tools\\video\\minimax_tokenplan_video.py tests\\contracts\\test_minimax_tokenplan_video.py -> passed
• python -m pytest tests\\contracts\\test_minimax_tokenplan_video.py -q -> 49 passed
• python -c "from tools.tool_registry import registry; registry.discover(); ..." -> minimax_tokenplan_video is discoverable as provider=minimax, capability=video_generation
• git merge-tree --write-tree HEAD origin/main -> clean merge tree

I did not find an actionable security issue beyond the secret-redaction bug above, and I did not see supply-chain risk in this diff. Requesting changes because the provider's public setup contract and secret handling need to be corrected before merge.

[yiyabo]

Thanks for the thorough review — all four findings are fixed in bd52eaa.

1. Token Plan key priority — _api_key() now checks MINIMAX_TOKEN_PLAN_API_KEY first, then falls back to MINIMAX_API_KEY. If a user has both keys set, the Token Plan route is chosen, not the generic one.

2. Alias in docs/errors — install_instructions, the missing-key error message, .env.example, and docs/PROVIDERS.md all now mention both MINIMAX_TOKEN_PLAN_API_KEY (preferred) and MINIMAX_API_KEY. No hidden config paths.

3. callback_url — Added to input_schema with type string and description. It was already forwarded by _build_payload(); now the schema declares it so registry/docs/agent planning see it.

4. _safe_error() empty-string bug — Rewritten to iterate both env vars (MINIMAX_TOKEN_PLAN_API_KEY, MINIMAX_API_KEY) and redact only non-empty values. No more str.replace("", "[redacted]") between every character. The token-plan alias is now redacted too.

python -m pytest tests/contracts/test_minimax_tokenplan_video.py -q  # 53 passed

Added 4 regression tests covering each fix:

• test_api_key_prefers_token_plan — both keys set, Token Plan wins
• test_safe_error_no_empty_string_bug — no key set, output not mangled
• test_safe_error_redacts_token_plan_key — token-plan alias redacted
• test_callback_url_declared_in_schema — schema declares callback_url

Happy to adjust if anything still looks off.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

docs/PROVIDERS.md:141

• The DashScope provider section lost its ### Alibaba DashScope — Qwen Image + TTS + ASR heading. After the MiniMax section separator (---), the DashScope section starts directly with a blockquote, which makes the docs harder to scan and breaks the table-of-contents style structure used elsewhere in this file.

---



> **Best for Chinese-language production.** One key unlocks Qwen-Image generation, Qwen-TTS Mandarin narration, and Qwen-ASR with word-level timestamps — the only DashScope path that provides word-level granularity for subtitle alignment.

**Tools unlocked:** `dashscope_image`, `dashscope_tts`, `dashscope_asr`

[calesthio]

Thanks for the follow-up fixes on the Token Plan provider. I re-reviewed the PR description, comments, previous requested-changes review, latest diff, and CI against docs/PR_REVIEW_GUIDE.md. The provider implementation direction is useful and the prior setup/redaction/schema blockers look addressed: Token Plan key priority, both env vars in errors/docs, callback_url in the schema, and safe secret redaction all have regression tests.\n\nValidation run locally on the PR head:\n- python -m pytest tests/contracts/test_minimax_tokenplan_video.py -q -> 53 passed\n- python -m py_compile tools/video/minimax_tokenplan_video.py tests/contracts/test_minimax_tokenplan_video.py -> passed\n\nOne docs regression still needs cleanup before merge: docs/PROVIDERS.md lost the ### Alibaba DashScope — Qwen Image + TTS + ASR section heading. The DashScope body now starts immediately after the new MiniMax section separator with the blockquote, so the providers doc no longer has a proper DashScope heading/section anchor. Provider docs are user-facing setup contract, so please restore that heading after the MiniMax section.\n\nI did not find remaining code, security, or supply-chain blockers in the provider itself; this should be ready once the docs section structure is repaired.

[yiyabo]

Restored the ### Alibaba DashScope — Qwen Image + TTS + ASR heading in 9e0a820. The DashScope section now has its proper heading after the MiniMax section separator, as it was before this PR.

### MiniMax Token Plan — Direct Hailuo Video API
...
---
### Alibaba DashScope — Qwen Image + TTS + ASR

This was the only remaining blocker from your latest review. Happy to merge once you confirm the docs structure looks right.