This reference describes requests, responses, and errors for developers using the video_generation service.

The compatibility baseline is the official MiniMax documentation for video generation and file upload.

Every request sends Authorization: Bearer <API_KEY> in the header. Request bodies use application/json except for file upload.

Overview

Create a video generation task

POST /v2/video_generation

Success response

Success returns HTTP 200 with a JSON body:

{"task_id":"1d6085ca-1d9a-4d61-a4a6-30e02079990f"}

Top-level fields

The current capability supports 768P, 24 FPS, MP4/H.264, text-only generation, and first/last-frame video generation. context_ir_enabled controls Context IR prompt optimization and defaults to true, so prompt optimization is enabled unless explicitly disabled.

Create example

curl -X POST "https://ecotoken.ecophase-ai.com/v2/video_generation" \
  -H "Authorization: Bearer ${VIDEO_API_KEY}" \
  -H "Idempotency-Key: video-create-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"MiniMax-H3",
    "content":[{"type":"text","text":"a cinematic sunrise over an alpine lake"}],
    "resolution":"768P",
    "duration":5,
    "ratio":"16:9"
  }'

content

Every content item has a required type:

Supported URL forms are public HTTP(S), mm_file://{file_id}, and strict Base64-encoded data:<media-type>;base64,<standard-base64> values. The entire JSON request body is at most 64 MiB. Upload large or reusable media first.

data:<media-type>;base64,<standard-base64> is a Data URL that embeds a small file directly in the JSON request, so it does not need to be uploaded first to obtain a public URL. - data: indicates that the value contains file data rather than a normal network address. - <media-type> is the file MIME type, such as image/png or audio/mpeg. - base64 is the fixed marker declaring Base64 encoding. - <standard-base64> is the original file encoded with standard Base64.

Roles are first_frame, last_frame, reference_image, reference_video, and reference_audio. A single image with no role defaults to first frame. Video and audio inputs use their corresponding reference roles.

Accepted scenes:

• text only;
• text + first frame;
• text + last frame;
• text + first and last frame;
• text + any valid combination of reference images/videos/audio.

Frame roles and reference roles are mutually exclusive. First and last frame may each occur at most once.

Media validation

ratio

• For T2VA, ratio is required and cannot be adaptive; it must be one of 21:9|16:9|4:3|1:1|3:4|9:16.
• For I2VA, the ratio is derived from the input: an omitted value, adaptive, or another otherwise-valid ratio is normalized to adaptive.
• For R2VA, the default is adaptive, and it can be changed to one of 21:9|16:9|4:3|1:1|3:4|9:16.

Query a single task

GET /v2/query/video_generation/{task_id}

Response format

{
  "task": {
    "id": "1d6085ca-1d9a-4d61-a4a6-30e02079990f",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1787788800,
    "updated_at": 1787789100,
    "content": {"url": "https://SHORT_LIVED_DOWNLOAD_URL"},
    "resolution": "768P",
    "duration": 8,
    "usage": {"input_image_count": 1},
    "ratio": "adaptive",
    "task_type": "generation",
    "modality": "video"
  }
}

Task response fields

Task status monitoring

We recommend using task.internal_status to monitor the precise processing phase. The MiniMax API field task.status does not distinguish every processing phase accurately.

task.context_ir fields:

Use task.content.url only after succeeded. The URL is short-lived and should not be persisted or cached for long periods.

task.context_ir reports enabled, status, original_prompt, optimized_prompt, token usage, started_at, completed_at, and an optional error. A Context IR failure fails the whole task and identifies failed_phase=context_ir.

Billing semantics

A video task is charged only when it succeeds:

• Only a terminal status of `succeeded` is charged at all: priced on the measured output seconds times the resolution tier, plus this run's Context IR call (context_ir.status=succeeded, billed per call per task).
• Any other terminal status (including `failed`, `cancelled`, and expiry) is free: output video, reference images, input audio/video, and the Context IR line are all waived. Prompt optimization is an intermediate step toward the video rather than a standalone deliverable, so no video means the whole pre-authorization is released.
• A task is entirely free in two cases: the video generation failed or was cancelled, and the Context IR stage itself failed (no prompt delivered).
• Retrying after a failure with a fresh idempotency key is therefore safe: a failure costs nothing. Resending with the same idempotency key does not re-execute the task and adds no charge (the original task is returned within 7 days).

List tasks

GET /v2/query/video_generation?page_num=&page_size=&filter.status=&filter.task_ids=&filter.model=

Tenant isolation is always applied. page_num defaults to 1; page_size defaults to 20 with a current maximum of 20. The list covers only tasks created in the most recent 7 days.

Query parameters support filter.status, filter.task_ids (repeat the parameter or use filter.task_ids[]; at most 100 lowercase canonical UUIDs), and filter.model. Response:

{
  "items": [
    {
      "id": "1d6085ca-1d9a-4d61-a4a6-30e02079990f",
      "model": "MiniMax-H3",
      "status": "succeeded",
      "created_at": 1787788800,
      "updated_at": 1787789100,
      "content": {"url": "https://SHORT_LIVED_DOWNLOAD_URL"},
      "resolution": "768P",
      "duration": 5,
      "usage": {},
      "ratio": "16:9",
      "task_type": "generation",
      "modality": "video"
    }
  ],
  "total": 1
}

total is the number of tasks matching the filters in the most recent 7 days.

Cancel or delete a task

DELETE /v2/video_generation/{task_id}

A queued task returns action=cancelled,status=cancelled only after cancellation is confirmed. While confirmation is pending, it remains queryable as queued and DELETE returns a retryable 503. If the first request used an Idempotency-Key, reuse that key when retrying. A running task cannot be cancelled and returns 400. A succeeded or failed terminal task can be logically removed from the compatibility list and returns action=deleted,status=deleted.

Success response body:

{
  "task_id": "1d6085ca-1d9a-4d61-a4a6-30e02079990f",
  "action": "cancelled",
  "status": "cancelled"
}

deleted describes the delete operation only; task.status in query responses never becomes deleted.

File upload and media management

Media is referenced through public HTTP(S) URLs or managed files. Five operations are provided, all scoped to the authenticated user's media space. Different API keys and workspaces for one user share that space. Another user only receives not-found responses and cannot infer whether a file exists.

File-management JSON responses reuse these objects:

Upload

POST /v1/files/upload, using multipart/form-data. It must contain one purpose=video_generation_input field and one file part named file, with no other fields. The full request is limited to 64 MiB. Invalid media returns HTTP 400 and is not retained. Reference the result as mm_file://{file_id}. Files are retained for one day by default and can be deleted earlier.

curl -X POST "https://ecotoken.ecophase-ai.com/v1/files/upload" \
  -H "Authorization: Bearer ${VIDEO_API_KEY}" \
  -H "Idempotency-Key: media-upload-001" \
  -F "purpose=video_generation_input" \
  -F "file=@./reference.mp4;type=video/mp4"

Success response:

{
  "file": {
    "file_id": 424010985738629,
    "bytes": 1234567,
    "created_at": 1788148800,
    "filename": "reference.mp4",
    "purpose": "video_generation_input"
  },
  "base_resp": {"status_code": 0, "status_msg": "success"}
}

List

GET /v1/files/list?purpose=video_generation_input

The success response contains all unexpired files owned by the current user:

{
  "files": [
    {
      "file_id": 424010985738629,
      "bytes": 1234567,
      "created_at": 1788148800,
      "filename": "reference.mp4",
      "purpose": "video_generation_input"
    }
  ],
  "base_resp": {"status_code": 0, "status_msg": "success"}
}

Retrieve a file

GET /v1/files/retrieve?file_id=424010985738629

{
  "file": {
    "file_id": 424010985738629,
    "bytes": 1234567,
    "created_at": 1788148800,
    "filename": "reference.mp4",
    "purpose": "video_generation_input",
    "download_url": "https://download.example/reference.mp4"
  },
  "base_resp": {"status_code": 0, "status_msg": "success"}
}

download_url is short-lived. Retrieve fresh metadata whenever a download is needed.

Download file content

GET /v1/files/retrieve_content?file_id=424010985738629

On success, the response body contains the file bytes with the corresponding Content-Type; it is not JSON. The client only sends its own EcoPhase API key.

Delete

POST /v1/files/delete. The delete request uses purpose=video_generation; upload and list continue to use video_generation_input.

{"file_id":424010985738629,"purpose":"video_generation"}

Success response:

{
  "file_id": 424010985738629,
  "base_resp": {"status_code": 0, "status_msg": "success"}
}

Deleting the same file_id and purpose again as the same user is idempotent.

Error envelope

Video generation uses the MiniMax-compatible error envelope:

{
  "type": "error",
  "error": {"type": "bad_request_error", "message": "...", "http_code": "400"},
  "request_id": "..."
}

Error response fields:

Idempotency

Video generation, file upload, and task deletion support an optional Idempotency-Key. The value must contain 1–128 safe ASCII characters and is scoped to the current endpoint, service, workspace, and authenticated user. Rotating an API key for the same user does not change replay identity. A video-create key remains active for seven days after the first successful creation.

After an operation completes, the same key and request return the previous result. The same key with different content returns 409. An identical request may also receive 409 while the first operation is still in progress; retry later with exactly the same key and request. Deleting a task does not release its original create key. Reusing the key after the window expires creates a new task.