# H3 Video Platform · HTTP API Reference For AI agents writing their own HTTP clients. If you use the `h3` CLI you don't need this file: the CLI wraps everything below. See [SKILL.md](https://minimax.xxt.ai/SKILL.md). Base URL: `https://minimax.xxt.ai`. All paths below are relative to it. ## 1. Conventions ### Authentication Send on every request: ``` Authorization: Bearer ``` - Get an API Key by having the user approve a link (see "Link authorization" in section 2; the user doesn't copy a key), or the user generates one on the "API Key" page (「API Key」) of the website; it is shown only once. It spends this account's credits and has the same permissions as the user on the website. - Wrong or revoked key: `401 invalid_api_key`. Banned account: `403 banned`. ### Requests and responses - Request bodies are JSON with `Content-Type: application/json`, max 64KB. Images and audio never go through these endpoints; they use upload URLs (section 3). - Responses are always JSON. Times are ISO 8601 UTC, e.g. `2026-10-25T08:00:00.000Z`. - Error body: ```json { "error": "insufficient_credits", "message": "可用积分不够。", "balance": 120, "required": 250 } ``` Decide what to do from `error` (the code). `message` is a human-readable Chinese explanation (here: "Not enough available credits."). Some errors carry extra fields (section 9). - Invalid parameters (`invalid-input`) include `issues`, saying which field is wrong and why: ```json { "error": "invalid-input", "message": "填的内容不对，请检查一下。", "issues": [ { "path": "seconds", "message": "时长要在 4–15 秒之间" }, { "path": "refs[0].note", "message": "角度选「其他」要填说明" } ] } ``` (Messages: "The input is invalid, please check it."; "Duration must be 4–15 seconds"; "Angle 'other' needs a note".) `path` is the request-body field (arrays as `[index]`); for a bad header it is the header name, e.g. `Idempotency-Key`. At most 10 issues are listed. ### CLI and skill versions Every response (errors included) carries two headers. `X-H3-Cli-Sha256` is the sha256 of the live `/h3.py`. `X-H3-Skill-Sha256` is the sha256 of the six skill files (`/SKILL.md`, `/references/prompting.md`, `/references/api.md`, `/references/songwriting.md`, `/references/characters.md`, `/references/motion-swap.md`, in that order, joined with one `\0` byte). A client that caches these files can compare and re-download on mismatch. The `h3` CLI auto-updates this way. `X-H3-Drama-Sha256` is the fingerprint of the short-drama skill packs (h3-drama, drama-finish, drama-mv), which need login: `GET /api/v1/skill-packs/drama` returns `{ bundle, sha256, packs: [{ name, files: [{ path, sha256, bytes }] }] }` and `GET /api/v1/skill-packs/drama//` one file as text (`404 not-found` for anything else). `h3 skill install drama` saves and updates them. ### Pagination List endpoints return `{ "items": [...], "next": "" | null }`. For the next page pass `next` back as `before`. `next` = `null` means no more. ### Retention period Videos, songs and uploaded files are kept for 8 hours after the job ends, then deleted automatically. Please download them in time. ## 2. Account ### `GET /api/v1/me` · My account ```json { "email": "a@example.com", "isAdmin": false, "balance": 500, "held": 250 } ``` - `balance`: available credits. `held`: credits on hold for submitted, not yet settled work. 1 credit = ¥0.01. ### `GET /api/v1/me/usage` · My usage Cumulative since signup. ```json { "jobs": 12, "videos": 15, "videoSeconds": 112.5, "creditsSpent": 2250, "videoCreditsSpent": 1650, "songRuns": 3, "songs": 5 } ``` - `jobs`: number of job submissions (successful or not). - `videos`: videos delivered. A two-take submission counts as two. Failed and canceled takes don't count. - `videoSeconds`: total seconds of delivered videos. - `creditsSpent`: total credits spent, i.e. the sum of all charges (videos and songs). Refunds don't count. - `videoCreditsSpent`: the part spent on videos (excluding songs). - `songRuns`: number of song submissions, one per submission (successful or not). - `songs`: songs received. Each run produces two; only finished ones count. ### `GET /api/v1/me/ledger?limit=50&before=` · Credit ledger Newest first. `limit` defaults to 50, max 200. ```json { "items": [ { "id": "42", "kind": "hold", "amount": 250, "delta": -250, "balanceAfter": 250, "heldAfter": 250, "note": null, "createdAt": "2026-10-25T08:00:00.000Z", "job": { "id": "…", "mode": "i2v", "seconds": 5, "segments": 1, "prompt": "提示词开头 30 个字…" }, "song": null } ], "next": "41" } ``` - `kind`: `signup` signup bonus; `admin_adjust` admin adjustment; `purchase` credits bought online (`note` is `订单 `, "order "); `hold` hold at submission (video or song); `charge` charge on success of a video or song (songs are charged per track, one entry per track); `release` refund on failure or cancel (also for a song track that didn't come out). - `amount`: the entry's amount (always ≥ 0). `delta`: change in available balance (negative for holds, positive for refunds, 0 for charges; a charge shows as a drop in `heldAfter`). - `job`: the related job (`job.prompt` is the first 30 characters of the prompt). `null` for songs, signup bonus and admin adjustments. - `song`: the related song run, `{ "id", "title" }` (`id` is the song run id, `title` the song title, `null` if untitled). `null` for non-song entries. - Other fields such as `holdId` and `apiKeyId` can be ignored. ### Buying credits (Stripe) The user pays on a Stripe payment page (card, or any other method the page offers); you only create the order and hand over the link. Credits arrive automatically after payment. Purchased credits don't expire and aren't refundable. | Endpoint | Purpose | Returns | |---|---|---| | `GET /api/v1/billing/options` | Packages, custom-amount limits and whether online payment is available | `{ "available": true, "packages": [{ "credits": 10000, "prices": { "CNY": 10000, "USD": 1500 } }], "custom": { "credits": { "min": 10000, "max": 1000000 }, "amount": { "CNY": { "min": 100, "max": 10000 }, "USD": { "min": 15, "max": 1500 } } } }`; package prices are in the smallest currency unit (fen, cents); `custom.amount` is in whole yuan / dollars | | `POST /api/v1/billing/checkout`, body `{ "credits": 10000, "currency": "CNY" }` | Create an order. `credits`: a package (10000 = ¥100 / $15, 50000 = ¥500 / $75, 100000 = ¥1000 / $150) or any custom integer from 10000 to 1000000 (¥100–¥10,000 / $15–$1,500). For a custom amount in money: CNY credits = yuan × 100; USD credits = floor(dollars ÷ 0.0015). Below 10000: `400 invalid-input` (`path` = `credits`); `currency` `CNY` (¥0.01 per credit) or `USD` ($0.0015 per credit) | `201 { "order": , "url": "https://checkout.stripe.com/…" }`. Give `url` to the user to open in a browser; don't open or pay it yourself. Not available: `503 payments_unavailable` | | `GET /api/v1/billing/orders` | My orders, newest first, max 50 | `{ "items": [] }` | | `GET /api/v1/billing/orders/` | One order; while still `pending` the platform checks with Stripe once, so a paid order turns `paid` right away | ``. Not yours: `404 not-found` | Order: `{ "id", "credits", "currency", "amount", "status", "createdAt", "paidAt" }`. `amount` is in the smallest currency unit. `status`: `pending` (waiting for payment), `paid` (credits added), `expired` (payment page expired after 24 hours unpaid; create a new order), `mismatch` (payment didn't match the order; no credits added; the user should email hi@xxt.ai). Don't create orders the user didn't ask for. Ask which package and currency first (Chinese users usually `CNY`). ### API Key management | Endpoint | Purpose | Returns | |---|---|---| | `GET /api/v1/keys` | List unrevoked keys | `[{ "id", "name", "prefix", "createdAt", "lastUsedAt", "totalCharged" }]` | | `POST /api/v1/keys`, body `{ "name": "笔记本" }` | Create one (name 1–64 chars; must be unique among unrevoked keys) | `201 { "id", "name", "key" }`; `key` appears only this once. Duplicate name: `409 name_taken` | | `DELETE /api/v1/keys/` | Revoke; takes effect immediately | `{ "ok": true }` | ### Link authorization (user doesn't copy a key) Works like device authorization (RFC 8628): you start a request and send the link to the user; the user logs in on the website and clicks Authorize (「授权」); you use the device code to receive a new API Key. The start and poll endpoints need no `Authorization`. | Endpoint | Purpose | Returns | |---|---|---| | `POST /api/v1/device-login`, body `{ "clientName": "MacBook-Pro" }` (optional, max 64 chars, shown on the authorization page) | Start | `201 { "deviceCode", "userCode", "verificationUrl", "verificationUrlComplete", "expiresIn": 600, "interval": 5 }` | | `POST /api/v1/device-login/token`, body `{ "deviceCode": "…" }` | Poll | Not yet approved: `{ "status": "pending" }`. Approved: `{ "status": "approved", "key", "keyId", "keyName" }`; `key` is returned only this once | | `GET /api/v1/device-login/` | Request details (login required) | `{ "userCode", "clientName", "clientCountry", "createdAt", "expiresAt", "status" }`. `clientCountry` is the country/region code of the requester (e.g. `SG`), `null` if unknown | | `POST /api/v1/device-login//approve` | Approve (login required; the key is created under this account) | `{ "ok": true }` | | `POST /api/v1/device-login//deny` | Deny (login required) | `{ "ok": true }` | - Send the user `verificationUrlComplete` (link with the code) and `userCode` (the confirmation code, e.g. `KMQT-WXBD`); ask them to check the code, then click Authorize. Keep `deviceCode` to yourself; never send it out. - Poll `token` every `interval` seconds. On `429 slow_down`, add 5 seconds to the interval. - `403 login_denied`: the user denied. `410 login_expired`: `expiresIn` seconds (10 minutes) passed, or the device code is wrong. Start over in both cases. - Polling is not idempotent: the key is created on the first poll after approval; later polls return `410 login_consumed` (with `keyName`). So don't auto-retry this request; on a network error wait one `interval` and poll again. - The key is named `h3 login · · MM-DD HH:mm` (Singapore time). It appears in `GET /api/v1/keys` and can be revoked any time. - Max 10 starts per IP per 10 minutes (IPv6 counted per /64); beyond that `429 too-many-requests`. - If an account enters a wrong code more than 20 times within 10 minutes, viewing details, approving and denying all return `429 too-many-requests` for that period. - The code is case-insensitive; spaces and dashes are ignored. Unknown or expired: `404 not-found`. Already approved or denied: `409 login_decided`. ## 3. Uploading assets Images and audio don't pass through the platform server: request an upload URL, then upload the file directly to it. ### Step 1: `POST /api/v1/uploads` · Request an upload URL ```json { "kind": "image", "contentType": "image/png", "size": 482133 } ``` - `kind`: `image`, `audio` or `video` (video is only for motion swap: MP4/MOV, at most 80MB, `duration` 2–180 s). - `contentType`: - images: `image/jpeg`, `image/png`, `image/webp`; - audio: `audio/mpeg`, `audio/wav`, `audio/mp4` (.m4a), `audio/aac`, `audio/flac`, `audio/ogg`; - video: `video/mp4`, `video/quicktime` (.mov). - Aliases are normalized, e.g. `audio/x-m4a`, `audio/mp3`, `image/jpg`. - `size`: file size in bytes. Images ≤ 10MB, audio ≤ 20MB, video ≤ 50MB. - `purpose`: optional, `job` (default), `character`, `voice` or `feedback`. `job` is a job asset, deleted automatically when it expires (see "Retention period"). Photos and recordings for the character library must use `"purpose": "character"`; those files are kept until you delete them (section 7). `voice` is for the two recordings used to create My Voice (WAV only: `kind` must be `audio`, `contentType` `audio/wav` or `audio/x-wav`, max 25MB each); they are deleted after use. See "My Voice" in section 8. `feedback` is for screenshots attached to a feedback note (images only, same types and 10MB limit as job images); once attached they are kept with the note, unattached ones are deleted after 6 hours. See section 10. - `duration`: required for video, not allowed otherwise. Video duration in seconds, 2–15.5. At submission it is used to check the requested length; the machine checks again against the real frame count before generating. Video can only be a job asset, not `"purpose": "character"`. - `thumb`: optional, images only. `"image/webp"` or `"image/jpeg"` (`true` means JPEG) also returns a `thumbPutUrl` for a small preview (≤ 1MB, short edge about 400px) that you make yourself; upload it like step 2 with that `Content-Type`. The website does this for character photos so long lists load fast. Not needed for jobs; without it the preview URL is just the original. - `width`, `height`: optional, images only. Width and height in pixels after EXIF rotation; send both together, each 1–20000. Sending them for audio returns 400 invalid-input. If given, the website can warn how much the first/last frame will be cropped; works without them too. Returns `201`: ```json { "id": "6f1c…", "putUrl": "https://h3-files.xxt.ai/…", "contentType": "image/png", "expiresAt": "…" } ``` With `"thumb": true` there is also `"thumbPutUrl"`. Errors: unsupported type `400 unsupported_type`; too large `413 file_too_large`; file service off `503 files_unavailable`. ### Step 2: `PUT ` · Upload the file ``` PUT Content-Type: Content-Length: ``` - Success: `201`. The upload URL is valid for 30 minutes and can be written once. - Errors in this step are plain text, not JSON: - `411`: no Content-Length; - `413`: larger than declared; - `415`: wrong Content-Type; - `409`: already uploaded, can't overwrite. If you were retrying after a network drop, the previous attempt actually succeeded; treat it as success. ### Asset preview URL: `GET /api/v1/uploads//file` Returns `{ "url", "expiresAt" }`, valid 1 hour. Asset not yet used in a job: `409 file_not_ready`. Already deleted: `410 file_expired`. If the image has a small preview there is also `"thumbUrl"` (it may 404 if the preview was never uploaded; fall back to `url`). To add a preview to an image uploaded without one: `POST /api/v1/uploads//thumb?contentType=image/webp` (or `image/jpeg`, the default) returns `201` `{ "putUrl", "contentType", "expiresAt" }`. A preview can be written once. Not an image: `400 unsupported_type`; deleted: `410 file_expired`. An asset id can be reused in other jobs during its retention period; no need to re-upload. ## 4. Submitting a job ### `POST /api/v1/jobs` Optional header `Idempotency-Key: <1–100 chars>`. Repeated submissions by the same user with the same key create only one job; repeats return the original (status `200`; a new job is `201`). **Send a fresh random key with every submission and reuse the same key when retrying after a network error**, so credits are never held twice. This applies only to job submission (`POST /api/v1/jobs`); song submission does not honor `Idempotency-Key` — see section 8 for how to retry. Body: | Field | Type | Description | |---|---|---| | `mode` | string, required | `lipsync` lip-sync; `i2v` image-to-video (first frame / first + last frame); `t2v` text-to-video (prompt only); `ref2v` free shot (reference images only, no first frame); `promo` promo video (one character hosts and talks about products; see "Promo video" below); `swap` motion swap (`refVideo` + 1–4 people in `people`, no `prompt`; see motion-swap.md). `GET /api/v1/modes` is authoritative | | `aspect` | string, required | `9:16` (portrait 768×1344), `16:9` (landscape 1344×768) or `1:1` (square 1024×1024) | | `seconds` | number, required | Duration, up to two decimals. Range per mode: `lipsync` 2–15, `i2v` 4–15, `t2v` 4–15, `ref2v` 4–15, `promo` 4–15, `swap` 2–60 (`modes` is authoritative) | | `segments` | 1 or 2 | Number of takes, default 1. 2 = one take each with two different methods (take A, take B) for the user to pick; credits for two. `ref2v`, `promo` and `swap` allow only 1 (`maxSegments` in `modes`) | | `resolution` | string | Default `768p`. `1080p` renders at 768p, then RTX-upscales to 1080×1920 (landscape 1920×1080, square 1440×1440); double credits | | `firstFrame` | asset id | First-frame image. Required for `lipsync` and `i2v`; not allowed for `t2v`, `ref2v`, `promo` | | `lastFrame` | asset id | Last-frame image, optional. `i2v` only | | `audio` | asset id | Vocal audio. Required for `lipsync`; not allowed in any other mode (including `promo`) | | `refs` | array | Reference images, max 8 (7 with a last frame), 3–5 recommended. Whenever a person is on screen, always include character or person reference images, lip-sync and first-frame modes included. Not allowed for `t2v` and `promo`; `ref2v` needs at least one (for products, scenes etc. use `other` and say what it is). Each item `{ "asset": "", "angle": "", "note": "" }` | | `characters` | array | Characters from the character library (section 7). Allowed in `i2v`, `ref2v`, `lipsync`, `promo` (`promo` needs exactly one, the host; `lipsync` needs exactly one, the person singing or speaking, can't send `lines`, and the sung words still go in `dialogue`). Each item `{ "character": "", "wardrobe": false, "angles": ["front", "side"], "position": "the young woman on the left" }`; order = character order; each character at most once. `angles` is optional: if given, only this character's photos at these angles are used (pick by the shot's camera angle, see "Picking photos" below); each angle once, `other` not allowed. If the character has no photo at a listed angle: `400 invalid-input` (`path` = `characters[i].angles[j]`). `wardrobe: true` also references the clothes; `ref2v` only (in `i2v` and `lipsync` clothes follow the first frame). `position` (≤ 60 characters, `i2v` with `promptMode: describe` only, otherwise `400 invalid-input`, `path` = `characters[i].position`): who this is and where they stand in the first frame, e.g. `左边穿米色毛衣的年轻女人`; when three or more characters all have one and there are `lines`, the platform names each speaker by position (prompting.md section 1). Characters + `refs` ≤ 8. **When characters are used, person photos come from the characters; `refs` hold only scenes, products and props**: every `angle` must be `other` with a `note` saying what it is; anything else is `400 invalid-input` (`path` = `refs[i].angle`) | | `lines` | array | Lines, one per utterance; requires characters in `characters`. Max 10, in speaking order. Each item `{ "character": "", "text": "", "action": "" }`: `text` required, 1–200 chars; `action` optional, max 200 chars; neither may contain `<`, `>` or newlines. At most 3 speaking characters per shot (`i2v` too). Can't be combined with `dialogue`; in `describe` with characters you can't use `dialogue` (use `lines`); in `raw` you can't use `lines` (write lines into the prompt). With characters and no `lines`, the platform extracts lines from quotes in `prompt` (see "Lines in the prompt" below); **better to split them yourself and send `lines`** | | `prompt` | string, required | `describe` 1–4000 chars, `raw` 1–8000 chars. Optional for `promo` (platform uses a default; see "Promo video"). In `describe` with characters and no `lines`, quoted text becomes lines; for promo without `sellingPoints`, selling points and wear are extracted too (see "Lines in the prompt"). How to write: [prompting guide](https://minimax.xxt.ai/references/prompting.md) | | `promptMode` | string | `describe` (default): a scene description, Chinese allowed; the platform translates it to English and wraps it in H3 format. `raw`: your own complete H3-format prompt, used as is; must contain `integrated_multimodal_description:` | | `dialogue` | string | The sung or spoken words, inserted verbatim (not translated); for lip-sync it must match the vocal word for word. Max 500 chars, no `<`, `>` or newlines. `describe` only; the platform writes it as `(S1)` plus `[language] text`, language detected from the text (Chinese, Japanese, Korean, otherwise English) | | `sound` | string | Ambient sound description, max 500 chars, no `<`, `>` or newlines. `describe` only | | `seed` | integer | Random seed, 1–2147483647. Random if omitted | | `products` | array | `promo` only, required. 1–4 products; see "Promo video" | | `scene` | object | `promo` only, optional. Scene image `{ "asset": "", "name": "" }`, `name` 1–40 chars | | `sellingPoints` | string | `promo` only, optional. Selling points, max 300 chars; the platform writes the host's pitch from them. Can't be combined with `lines`. If neither is sent and `prompt` is given, the platform extracts selling points from `prompt` | | `refVideo` | asset id | `swap` only, required: the motion video (`kind: video`, 2–180 s; the output is at most 60 s for now). `seconds` (counted from the start) can't exceed its length (within 0.25 s is accepted), otherwise `400 ref_video_too_short` | | `people` | array | `swap` only, required: the people to swap in, 1–4, in order (`` numbering follows this order): each `{ "photos": ["", …] }` (1–4 photos of the same person: front face, three-quarter face, full body look most alike), `{ "photo": "" }` or `{ "character": "" }` (the platform uses its `full_front`, `front` and three-quarter photos), with an optional `role` (who they replace, ≤ 60 chars, no `<`, `>` or newlines). **All people's photos together at most 9** (uploaded photos over 9 → `400 invalid-input`; characters' photos are trimmed to fit, last angles first). One person: the role decides which shots have them, and in those shots the biggest person is redrawn. 2–4 people: everyone in each shot is tracked and matched to a person by the vision model (give each a role); matched people are redrawn in one pass, everyone else is kept. A full-body photo works best: the outfit comes from it | | `noLipSync` | boolean | `swap` only. Default `false` (mouths follow singing or speech in the original audio); `true` when nobody in the video sings or talks | | `keepRefAudio`, `feedRefAudio` | boolean | Old motion-swap fields, no longer accepted (`swap` always uses the original audio) | | `part` | object | `promo` only, optional. Which part this is when long content is split: `{ "index": 2, "total": 6 }`, 1-based, `index` ≤ `total`, `total` ≤ 20 | When characters are used, the platform does this: - **Picking photos**: max 8 photos total, 7 with a last frame (the model takes at most 9 images; first and last frame use one each; `refs.maxWithLastFrame` in `GET /api/v1/modes`). `refs` take their slots first; characters get the rest. A character with `angles` is picked only from photos at those angles (front photo still first, the rest in `angles` order). Recommended: always include `front`; add `side` or a three-quarter angle for profile shots, `full_back` for shots from behind. Each character first gets one front (`front`) photo, or its first photo if it has none. Then characters take turns in character order, one more photo each in their photo order, until the slots are full or photos run out (same for `ref2v`, `i2v`, `lipsync`). E.g. 2 characters plus 2 scene/prop images: 3 photos per character. 1 character and no `refs`: all its photos are used. - **Image numbering**: character photos in character order, each character in picked order; `refs` follow all character photos. `ref2v` starts at ``. In `i2v` and `lipsync` the first frame is ``, character photos start at 2, and the last frame comes after all other images. - **Scene, product and prop images**: in `ref2v` each `refs` image is its own subject, numbered after the characters (from ``). In the prompt just mention what its `note` says, e.g. the character sits in the "café" holding the "red cup". - **Voice numbering**: `