Generate Videos with Claude Code or Codex: MiniMax H3 from Your Terminal

What you need

• An XXT account: sign in with your email and it is created automatically. New accounts get 500 free credits.
• An agent that can run shell commands: Claude Code, Codex, or another local agent.
• Python 3.9 or later. The macOS system Python works; Windows works with python h3.py.
• Optional: ffmpeg, if you want the agent to join several clips into one video.

Step 1: Hand your agent one sentence

Paste this into your agent, in the language you want it to answer in:

Read https://minimax.xxt.ai/SKILL.md, install the h3 CLI and run h3 login, then send me the sign-in link it gives you. Once I approve it, make videos for me.

The SKILL.md it reads is written for agents: which mode to pick, how to write prompts, how credits work and what each error means. You don't need to read it yourself.

Step 2: Approve the sign-in link

The agent installs the CLI. It is a single Python file using only the standard library:

mkdir -p ~/.local/bin
curl -fsSL https://minimax.xxt.ai/h3.py -o ~/.local/bin/h3 && chmod +x ~/.local/bin/h3
h3 login --no-wait

h3 login returns a link and a short code, which the agent sends you. Open the link, sign in with Google or a one-time email code if needed, check that the code matches, and approve. The agent now holds its own API key for your account; you never copy a key, and you can revoke it on the API Keys page at any time.

Step 3: Ask for a video

Describe what you want in plain words, and attach images or a voice track if you have them. The agent picks the mode, writes the prompt in English following our prompting rules, and tells you how many credits the job will hold before it submits. Its instructions say to ask you first above 1,000 credits or before a batch of jobs.

h3 submit --mode i2v --first-frame shot1.png --aspect 9:16 --seconds 6 \
  --prompt "A medium shot frames the girl standing by the river at dusk. She slowly turns her head toward the camera and smiles softly as the evening breeze lifts her hair. The camera holds a static shot." \
  --wait --out ./out

Every command prints JSON, and local files are uploaded automatically. When the job finishes, the agent gives you the full path of each downloaded file. Other commands it uses: h3 jobs (recent jobs), h3 wait <job-id>, h3 pull <job-id>, h3 cancel <job-id> (held credits are refunded), h3 me (balance) and h3 ledger (credit history).

Videos, songs and uploaded files are kept for 8 hours after the job ends, then deleted automatically. Please download them in time.

Keep the instructions installed

h3 skill install saves SKILL.md and its reference files to ~/.claude/skills/h3-video/, so Claude Code picks them up as a skill. For another agent add --host: codex (the shared ~/.agents/skills folder, which Cursor, Gemini CLI, OpenCode and GitHub Copilot also read), cursor, gemini, opencode, copilot, or all (Claude Code plus the shared folder); --dir for any other place. The CLI updates itself and the saved files when a new version comes out.

h3 skill install                 # Claude Code
h3 skill install --host codex    # Codex, Cursor, Gemini CLI and others

What the agent can make

• Text to video, from a description alone.
• First frame, or first and last frame, to video: bring an image to life.
• Free shot: no first frame; saved characters or a few photos, the face stays the same from shot to shot. See character consistency.
• Lip sync: a photo sings or talks to a voice track. See lip sync.
• Promo videos: a character hosts and pitches products; longer videos are made in parts and joined with h3 concat.
• Songs: lyrics and a style in, 2 tracks out per run.

Videos are 4–60 seconds, in 9:16, 16:9 or 1:1, at 768P or 1080P.

Why a CLI instead of an MCP server

• Nothing to run in the background: one file, standard library only.
• Any agent that can run shell commands can use it, with the same instructions.
• JSON output and clear exit codes: 0 success, 1 API or network error, 2 bad usage, 3 job failed or canceled, 4 still running when the wait timed out (run the wait again).
• Writing your own client instead? The same features are in the HTTP API.

Cost and time

Video costs $0.009 per second at night (22:00–10:00 Singapore Time) and $0.0135 per second during the day, up to 80% below the official MiniMax API. 1080P costs double. Credits are held when the job is submitted, charged only if the video is made, and refunded if it fails.

A 6-second 768P video takes about 3 min once generation starts, plus any time in the queue. The agent waits and checks the status for you.

FAQ