Requirements
- An AI Video Maker account and an active key from Account → API Keys
- Creating your first API key grants 50 introductory credits once per account
- Keep the key in
AIVIDEO_API_KEY; do not put it in URLs, source code, analytics, or logs
API generation requires credits, not a website subscription. It currently draws from your account's shared available credit balance. Website subscription entitlements do not provide unlimited API generation.
Connect an agent without copying an API key
For Codex, Claude Code, or OpenClaw, install the AI Video Maker skill and ask the agent to connect your account. It starts a browser approval flow: sign in, compare the code with the one shown by your agent, and approve. The helper saves the connection privately and verifies your account and a sample quote without spending credits. No video is generated during setup.
You can revoke the agent key or set limits in API key settings. If browser connection is unavailable, the skill includes connect.mjs --manual for hidden key entry in your own terminal. Never paste a key into agent chat.
Check setup
Use the non-billable doctor endpoint before the first generation. It validates the key and returns the current balance, key limits, credit warning, and supported models.
curl 'https://aivideomaker.ai/api/v1/account' \
--header "key: $AIVIDEO_API_KEY"
Quote before spending
The quote endpoint validates field types, supported values, and defaults, then runs the same price calculation as generation without creating a task or charging credits. A quote does not check media accessibility, content safety, or whether frame inputs and reference assets can be combined. Those checks happen during task processing and can still cause an accepted task to fail.
curl --request POST 'https://aivideomaker.ai/api/v1/quote/minimax' \
--header 'Content-Type: application/json' \
--header "key: $AIVIDEO_API_KEY" \
--data '{"content":"A cinematic close-up of a candle on a wooden table.","duration":5,"resolution":"720p","tier":"turbo","aspectRatio":"16:9"}'
The response includes credits, listPriceUsd, currentBalance, affordable, and billable: false.
For this payload, the quote is 15 credits ($0.15). affordable only compares that cost with your current balance; it does not reserve credits or check your API key's daily spending and generation-rate limits. Submission checks those limits and the available balance again.
Submit a MiniMax H3 task
Choose an idempotency key for this generation and save it before submitting. The example below is one logical request: use a new value for each new video, and keep the same value and request body for retries.
curl --request POST 'https://aivideomaker.ai/api/v1/generate/minimax' \
--header 'Content-Type: application/json' \
--header "key: $AIVIDEO_API_KEY" \
--header 'Idempotency-Key: candle-demo-001' \
--header 'X-Max-Credits: 15' \
--data '{"content":"A cinematic close-up of a candle on a wooden table.","duration":5,"resolution":"720p","tier":"turbo","aspectRatio":"16:9"}'
A newly accepted submission returns HTTP 200 and is queued for processing:
{
"status": "SUBMITTED",
"taskId": "ckxxxxxxxx",
"creditsCharged": 15,
"idempotentReplay": false,
"responseUrl": "https://aivideomaker.ai/api/v1/tasks/ckxxxxxxxx",
"statusUrl": "https://aivideomaker.ai/api/v1/tasks/ckxxxxxxxx/status",
"cancelUrl": "https://aivideomaker.ai/api/v1/tasks/ckxxxxxxxx/cancel"
}
Credits are debited when the task is accepted, before asynchronous content checks and provider submission. A processing failure marks the task FAILED and triggers a refund; inspect task details for output.error and creditsRefunded.
With the same API key, an identical retry returns the original task without a second charge. Its status may already be PROGRESS, COMPLETED, FAILED, or CANCEL, and idempotentReplay will be true. creditsCharged reports the original task charge, not an additional debit. Reusing the idempotency key with different inputs returns HTTP 409.
X-Max-Credits rejects a new request with HTTP 422 before billing if the calculated cost exceeds the limit. The value 15 approves only the example above; quote again and choose an appropriate limit if you change the payload.
Poll status
Replace ckxxxxxxxx with the returned taskId, or use statusUrl directly. Use the API key that created the task; another key on the same account cannot read it.
curl 'https://aivideomaker.ai/api/v1/tasks/ckxxxxxxxx/status' \
--header "key: $AIVIDEO_API_KEY"
The status endpoint returns an object such as {"status":"PROGRESS"}. Possible values are SUBMITTED, PROGRESS, COMPLETED, FAILED, and CANCEL. Poll while the task is SUBMITTED or PROGRESS; stop on any terminal status.
Account checks, quotes, task reads, and cancellations share a limit of 60 requests per minute per IP. Poll every few seconds and honor HTTP 429 and its Retry-After header. Generation requests have a separate per-key rate limit.
Retrieve the video
After the status is COMPLETED, request task details:
curl 'https://aivideomaker.ai/api/v1/tasks/ckxxxxxxxx' \
--header "key: $AIVIDEO_API_KEY"
An abbreviated completed-task response is shown below. The full response also includes createdAt, input, creditsCharged, creditsRefunded, listValueCents, and idempotencyKey.
{
"id": "ckxxxxxxxx",
"model": "minimax",
"status": "COMPLETED",
"output": {
"url": "https://example.com/generated-video.mp4",
"msg": "The file will only be saved for 24 hours, please download it promptly."
},
"completedAt": "2026-09-05T12:00:00.000Z"
}
Download completed output promptly. The current task response states that the file is retained for 24 hours.
Use the returned output.url to download the video; https://example.com/generated-video.mp4 above is a placeholder. For failure recovery and cancellation, see task lifecycle and errors.
Pricing
One API credit is USD $0.01. MiniMax H3 costs $0.03/second at 720p Turbo, $0.04/second at 720p Base or 1080p Turbo, and $0.05/second at 1080p Base. A 5-second 720p Turbo clip is 15 credits ($0.15); a 10-second clip is 30 credits ($0.30). See the MiniMax H3 contract.