EcoPhase is compatible with the MiniMax-H3 V2 video generation format, supporting text-to-video (T2VA), image-to-video (I2VA), and multimodal reference-to-video (R2VA). Every output is currently fixed at 768P, 24 FPS, MP4/H.264, and 4–15 seconds; 2K is not yet provided. For complete request/response formats, see the API reference.

Video generation is not currently billed, but requests still require a video_generation service API key and are subject to tenant and credential rate limits.

Endpoint and authentication

Create an API key on the "API access" page of the video generation console.

export VIDEO_API_BASE_URL="https://ecotoken.ecophase-ai.com"
export VIDEO_API_KEY="YOUR_VIDEO_GENERATION_API_KEY"

Create jobs with POST /v2/video_generation.

Idempotency-Key is an EcoPhase safe-retry extension: the same key with the same request returns the same job, and the same key with a different request returns 409. If the outcome is unknown, retry with the original key and exactly the same request body.

Prompt optimization (Context IR)

Before submitting for video generation, EcoPhase uses Context IR to automatically optimize the prompt for better output quality. The request passes through the context_ir_queued → context_ir_running stages, and the optimized prompt is retrievable via the query endpoint at task.context_ir.optimized_prompt; a Context IR failure fails the whole task (failed_phase=context_ir).

Enabled by default. Control it with the top-level context_ir_enabled field, an optional boolean defaulting to true:

• true (default): Context IR is enabled; the prompt is optimized before video generation. The call is billed per task once the task succeeds; a failed or cancelled task is free.
• false: Context IR is disabled; prompt optimization is skipped and the raw prompt is submitted directly to video generation. The task skips the Context IR stages and no Context IR line is billed.

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "A misty mountain valley at dawn, slow camera push forward"}
  ],
  "resolution": "768P",
  "duration": 5,
  "ratio": "16:9",
  "aigc_watermark": false,
  "context_ir_enabled": false
}

Text to video (T2VA)

content contains exactly one non-empty text item. T2VA requires one of the six fixed ratios below; adaptive is not valid for T2VA.

curl "https://ecotoken.ecophase-ai.com/v2/video_generation" \
  -H "Authorization: Bearer $VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {"type": "text", "text": "A misty mountain valley at dawn, slow camera push forward"}
    ],
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9",
    "aigc_watermark": false
  }'

Image to video (I2VA)

Use image_url items within content. The first_frame and last_frame roles are each optional and at most one of each. Each image is at most 30 MiB. The aspect ratio is derived from the frame (from the first frame, or from the last frame when only it is provided), so I2VA always uses ratio: "adaptive". Frame roles cannot be mixed with reference_image, reference_video, or reference_audio. In EcoWeb, uploading a first frame switches to image-to-video automatically; no separate mode selection is needed.

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "The subject turns toward the camera while the background lights shimmer"},
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {"url": "https://YOUR_ALLOWED_MEDIA_HOST/first-frame.png"}
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": {"url": "https://YOUR_ALLOWED_MEDIA_HOST/last-frame.png"}
    }
  ],
  "resolution": "768P",
  "duration": 8,
  "ratio": "adaptive",
  "aigc_watermark": false
}

Multimodal reference to video (R2VA)

Multimodal reference mode uses reference_image, reference_video, and reference_audio. They may be combined in any non-empty combination in the same content, but cannot be mixed with first/last-frame mode.

All reference videos may total at most 15 seconds, and all reference audio may independently total at most 15 seconds. The two limits are calculated separately, so 15 seconds of reference video and 15 seconds of reference audio may be used together. These limits follow the MiniMax-H3 V2 input media specification and the currently published console capability.

ratio may be omitted and defaults to adaptive, or it may name a fixed ratio. Omission or adaptive selects 768P 16:9 (1344×768).

{
  "model": "MiniMax-H3",
  "content": [
    {"type": "text", "text": "Preserve the subject, camera motion, and music pacing of the references"},
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {"url": "https://YOUR_ALLOWED_MEDIA_HOST/subject.png"}
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {"url": "https://YOUR_ALLOWED_MEDIA_HOST/motion.mp4"}
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {"url": "https://YOUR_ALLOWED_MEDIA_HOST/music.wav"}
    }
  ],
  "resolution": "768P",
  "duration": 10,
  "ratio": "adaptive",
  "aigc_watermark": false
}

Local file uploads

The MiniMax-H3 request body references media through image_url, video_url, or audio_url. When you select a local image, video, or audio file in EcoWeb, the page uploads it automatically and submits the job.

You may also pass a publicly reachable http or https media URL. Loopback and private-network addresses are rejected, and the published timeout and file-size limits apply.

Success response

HTTP 200 returns:

{
  "task_id": "YOUR_TASK_ID"
}

Use the task_id to query the job or list jobs.

Parameter rules

Clients cannot select a node, GPU, workflow, or internal deployment ID.

Errors, idempotency, and limits

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

• 400: invalid JSON, fields, media roles, capability parameters, or current job operation; the job does not exist, belongs to another tenant, or was removed from the compatibility view.
• 401: missing, invalid, not-yet-active, or revoked API key.
• 403: the API key lacks the required service or scope permission.
• 409: the same idempotency key maps to different content, or a state transition conflicts.
• 415: the request body is not application/json.
• 429: a tenant or credential rate/capacity limit was reached; honor Retry-After before retrying.
• 503 or 504: the video generation service is temporarily unavailable or timed out.

Do not automatically retry a create request with an unknown outcome and no idempotency key. Never write API keys, signed media URLs, or download URLs into logs, browser code, or source repositories.