minimax/h3-developer/reference-to-video

이미지를 비디오로

DEV

MiniMax H3 Developer Reference-to-Video API by MiniMax

minimax/h3-developer/reference-to-video

Reference-to-video

MiniMax H3-Developer self-hosted reference-to-video: generate a video that keeps the subject from one or more reference images/videos, driven by a text prompt, with generated audio. Supports 480P768P/2K.

MiniMax H3 Developer Reference-to-Video은(는) MiniMax에서 개발한 모델입니다. Atlas Cloud(운영: Atlas Cloud AI LLC)는 해당 모델에 대한 액세스를 제공할 뿐이며 이를 소유하지 않습니다. 모든 상표는 각 소유자에게 귀속됩니다.

입력

프롬프트 *

참조 자료 *(0/9)

파일을 드래그 앤 드롭하거나 클릭하여 업로드할 수 있습니다

MAX:9

해상도 *

길이 *

화면 비율

Prompt expansion

출력

대기

생성된 비디오가 여기에 표시됩니다

설정을 구성하고 실행을 클릭하여 시작하세요

요청당 $0.015가 소요됩니다. $10로 이 모델을 약 666번 실행할 수 있습니다.

다음으로 할 수 있는 작업:

Seedance 2.0 Kling v3 Vidu Wan2.7

파라미터

코드 예시
import requests
import time

# Step 1: Start video generation
generate_url = "https://api.atlascloud.ai/api/v1/model/generateVideo"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer $ATLASCLOUD_API_KEY"
}
data = {
    "model": "minimax/h3-developer/reference-to-video",  # Required. model name
    "prompt": "A beautiful sunset over the ocean with gentle waves",  # Required. The text prompt describing the video to generate
    "refers": [
        {
            "url": "example_url",
            "type": "example_type"
        }
    ],  # Required. Reference materials that anchor the generation
    "resolution": "768P",  # Required. The resolution of the generated video. options: 480P | 768P | 1440p-sr | 4k-sr
    "duration": 8,  # Required. The duration of the generated video in seconds
    "ratio": "adaptive",  # The aspect ratio of the generated video
    "prompt_expansion": False,  # Whether to expand the prompt for better results
}

generate_response = requests.post(generate_url, headers=headers, json=data)
generate_result = generate_response.json()
prediction_id = generate_result["data"]["id"]

# Step 2: Poll for result
poll_url = f"https://api.atlascloud.ai/api/v1/model/prediction/{prediction_id}"

def check_status():
    while True:
        response = requests.get(poll_url, headers={"Authorization": "Bearer $ATLASCLOUD_API_KEY"})
        result = response.json()

        if result["data"]["status"] in ["completed", "succeeded"]:
            print("Generated video:", result["data"]["outputs"][0])
            return result["data"]["outputs"][0]
        elif result["data"]["status"] == "failed":
            raise Exception(result["data"]["error"] or "Generation failed")
        else:
            # Still processing, wait 2 seconds
            time.sleep(2)

video_url = check_status()

설치

사용하는 언어에 필요한 패키지를 설치하세요.

pip install requests

인증

모든 API 요청에는 API 키를 통한 인증이 필요합니다. Atlas Cloud 대시보드에서 API 키를 받을 수 있습니다.

export ATLASCLOUD_API_KEY="your-api-key-here"

HTTP 헤더

import os

API_KEY = os.environ.get("ATLASCLOUD_API_KEY")
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

API 키를 안전하게 보관하세요

클라이언트 측 코드나 공개 저장소에 API 키를 노출하지 마세요. 대신 환경 변수 또는 백엔드 프록시를 사용하세요.

요청 제출

import requests

url = "https://api.atlascloud.ai/api/v1/model/generateVideo"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer $ATLASCLOUD_API_KEY"
}
data = {
    "model": "your-model",
    "prompt": "A beautiful landscape"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

요청 제출

비동기 생성 요청을 제출합니다. API는 상태 확인 및 결과 조회에 사용할 수 있는 예측 ID를 반환합니다.

POST/api/v1/model/generateVideo

요청 본문

import requests

url = "https://api.atlascloud.ai/api/v1/model/generateVideo"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer $ATLASCLOUD_API_KEY"
}

data = {
    "model": "minimax/h3-developer/reference-to-video",
    "prompt": "A beautiful sunset over the ocean with gentle waves"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(f"Prediction ID: {result['data']['id']}")
print(f"Status: {result['data']['status']}")

응답

{
  "code": 200,
  "data": {
    "id": "pred_abc123",
    "status": "processing",
    "model": "model-name",
    "created_at": "2025-01-01T00:00:00Z"
  }
}

상태 확인

예측 엔드포인트를 폴링하여 요청의 현재 상태를 확인합니다.

GET/api/v1/model/prediction/{prediction_id}

폴링 예시

import requests
import time

prediction_id = "pred_abc123"
url = f"https://api.atlascloud.ai/api/v1/model/prediction/{prediction_id}"
headers = { "Authorization": "Bearer $ATLASCLOUD_API_KEY" }

while True:
    response = requests.get(url, headers=headers)
    result = response.json()
    status = result["data"]["status"]
    print(f"Status: {status}")

    if status in ["completed", "succeeded"]:
        output_url = result["data"]["outputs"][0]
        print(f"Output URL: {output_url}")
        break
    elif status == "failed":
        print(f"Error: {result['data'].get('error', 'Unknown')}")
        break

    time.sleep(3)

상태 값

processing요청이 아직 처리 중입니다.

completed생성이 완료되었습니다. 출력을 사용할 수 있습니다.

succeeded생성이 성공했습니다. 출력을 사용할 수 있습니다.

failed생성에 실패했습니다. 오류 필드를 확인하세요.

완료 응답

{
  "data": {
    "id": "pred_abc123",
    "status": "completed",
    "outputs": [
      "https://storage.atlascloud.ai/outputs/result.mp4"
    ],
    "metrics": {
      "predict_time": 45.2
    },
    "created_at": "2025-01-01T00:00:00Z",
    "completed_at": "2025-01-01T00:00:10Z"
  }
}

파일 업로드

Atlas Cloud 스토리지에 파일을 업로드하고 API 요청에 사용할 수 있는 URL을 받습니다. multipart/form-data를 사용하여 업로드합니다.

POST/api/v1/model/uploadMedia

업로드 예시

import requests

url = "https://api.atlascloud.ai/api/v1/model/uploadMedia"
headers = { "Authorization": "Bearer $ATLASCLOUD_API_KEY" }

with open("image.png", "rb") as f:
    files = {"file": ("image.png", f, "image/png")}
    response = requests.post(url, headers=headers, files=files)

result = response.json()
download_url = result["data"]["download_url"]
print(f"File URL: {download_url}")

응답

{
  "data": {
    "download_url": "https://storage.atlascloud.ai/uploads/abc123/image.png",
    "file_name": "image.png",
    "content_type": "image/png",
    "size": 1024000
  }
}

입력 Schema

다음 파라미터를 요청 본문에서 사용할 수 있습니다.

전체: 7필수: 5선택: 2

modelstringrequired

model name

Default: "minimax/h3-developer/reference-to-video"

promptstringrequired

The text prompt describing the video to generate.

refersarray[object]required

Reference materials that anchor the generation. Any mix of reference images, videos, and audio, each as a public URL. At least one image OR video is required (audio alone is not allowed). Image formats: png, jpeg, jpg, webp; video: mp4, mov; audio: mp3, wav. 'type' is optional — when omitted it is inferred from the URL extension.

Min items: 1

urlstringrequired

Public URL of the reference image / video / audio.

typestring

Media kind. Optional; inferred from the URL when omitted.

imagevideoaudio

resolutionstringrequired

The resolution of the generated video.

Default: "768P"

480P768P1440p-sr4k-sr

durationnumberrequired

The duration of the generated video in seconds.

Default: 8

456789101112131415

ratiostring

The aspect ratio of the generated video. Use 'adaptive' to let the model choose.

Default: "adaptive"

adaptive21:916:94:31:13:49:16

prompt_expansionboolean

Whether to expand the prompt for better results.

Default: false

요청 본문 예시

{
  "model": "minimax/h3-developer/reference-to-video",
  "prompt": "A beautiful landscape",
  "refers": [
    {
      "url": "example_url",
      "type": "example_type"
    }
  ],
  "resolution": "768P",
  "duration": 8,
  "ratio": "adaptive",
  "prompt_expansion": false
}

출력 Schema

API는 생성된 출력 URL이 포함된 예측 응답을 반환합니다.

created_atstring

ISO timestamp of when the request was created (e.g., “2023-04-01T12:34:56.789Z”).

idstring

Unique identifier for the prediction, the ID of the prediction to get.

modelstring

Model ID used for the prediction.

outputsarray

Array of URLs to the generated content (empty when status is not completed).

statusstring

Status of the task: created, processing, completed, or failed.

응답 예시

{
  "id": "pred_abc123",
  "status": "completed",
  "model": "model-name",
  "outputs": [
    "https://storage.atlascloud.ai/outputs/result.mp4"
  ],
  "metrics": {
    "predict_time": 45.2
  },
  "created_at": "2025-01-01T00:00:00Z",
  "completed_at": "2025-01-01T00:00:10Z"
}

Atlas Cloud Skills

Atlas Cloud Skills는 400개 이상의 AI 모델을 AI 코딩 어시스턴트에 직접 통합합니다. 한 번의 명령으로 설치하고 자연어로 이미지, 동영상 생성 및 LLM과 대화할 수 있습니다.

지원 클라이언트

Claude Code

OpenAI Codex

Gemini CLI

Cursor

Windsurf

VS Code

Trae

GitHub Copilot

Cline

Roo Code

Amp

Goose

Replit

40+ 지원 클라이언트

설치

npx skills add AtlasCloudAI/atlas-cloud-skills

API 키 설정

Atlas Cloud 대시보드에서 API 키를 받아 환경 변수로 설정하세요.

export ATLASCLOUD_API_KEY="your-api-key-here"

기능

설치 후 AI 어시스턴트에서 자연어를 사용하여 모든 Atlas Cloud 모델에 접근할 수 있습니다.

이미지 생성Nano Banana 2, Z-Image 등의 모델로 이미지를 생성합니다.

동영상 제작Kling, Vidu, Veo 등으로 텍스트나 이미지에서 동영상을 만듭니다.

LLM 채팅Qwen, DeepSeek 등 대규모 언어 모델과 대화합니다.

미디어 업로드이미지 편집 및 이미지-동영상 변환 워크플로우를 위해 로컬 파일을 업로드합니다.

더 알아보기

github.com/AtlasCloudAI/atlas-cloud-skills

MCP Server

Atlas Cloud MCP Server는 Model Context Protocol을 통해 IDE와 400개 이상의 AI 모델을 연결합니다. MCP 호환 클라이언트에서 사용할 수 있습니다.

지원 클라이언트

Cursor

VS Code

Windsurf

Claude Code

OpenAI Codex

Gemini CLI

Cline

Roo Code

100+ 지원 클라이언트

설치

npx -y atlascloud-mcp

설정

다음 설정을 IDE의 MCP 설정 파일에 추가하세요.

{
  "mcpServers": {
    "atlascloud": {
      "command": "npx",
      "args": [
        "-y",
        "atlascloud-mcp"
      ],
      "env": {
        "ATLASCLOUD_API_KEY": "your-api-key-here"
      }
    }
  }
}

사용 가능한 도구

atlas_generate_image텍스트 프롬프트로 이미지를 생성합니다.

atlas_generate_video텍스트나 이미지로 동영상을 만듭니다.

atlas_chat대규모 언어 모델과 대화합니다.

atlas_list_models400개 이상의 사용 가능한 AI 모델을 탐색합니다.

atlas_quick_generate최적 모델을 자동 선택하여 한 번에 콘텐츠를 생성합니다.

atlas_upload_mediaAPI 워크플로우를 위해 로컬 파일을 업로드합니다.

더 알아보기

github.com/AtlasCloudAI/mcp-server

API 스키마

{
  "components": {
    "schemas": {
      "Input": {
        "properties": {
          "model": {
            "type": "string",
            "description": "model name",
            "default": "minimax/h3-developer/reference-to-video"
          },
          "prompt": {
            "description": "The text prompt describing the video to generate.",
            "type": "string"
          },
          "refers": {
            "description": "Reference materials that anchor the generation. Any mix of reference images, videos, and audio, each as a public URL. At least one image OR video is required (audio alone is not allowed). Image formats: png, jpeg, jpg, webp; video: mp4, mov; audio: mp3, wav. 'type' is optional — when omitted it is inferred from the URL extension.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": {
                  "type": "string",
                  "description": "Public URL of the reference image / video / audio.",
                  "x-ui-component": "uploaders"
                },
                "type": {
                  "type": "string",
                  "description": "Media kind. Optional; inferred from the URL when omitted.",
                  "enum": [
                    "image",
                    "video",
                    "audio"
                  ]
                }
              },
              "required": [
                "url"
              ]
            },
            "minItems": 1,
            "x-ui-component": "uploaders"
          },
          "resolution": {
            "default": "768P",
            "description": "The resolution of the generated video.",
            "enum": [
              "480P",
              "768P",
              "1440p-sr",
              "4k-sr"
            ],
            "type": "string",
            "x-ui-component": "select"
          },
          "duration": {
            "default": 8,
            "description": "The duration of the generated video in seconds.",
            "enum": [
              4,
              5,
              6,
              7,
              8,
              9,
              10,
              11,
              12,
              13,
              14,
              15
            ],
            "type": "number",
            "x-ui-component": "select"
          },
          "ratio": {
            "default": "adaptive",
            "description": "The aspect ratio of the generated video. Use 'adaptive' to let the model choose.",
            "enum": [
              "adaptive",
              "21:9",
              "16:9",
              "4:3",
              "1:1",
              "3:4",
              "9:16"
            ],
            "type": "string",
            "x-ui-component": "select"
          },
          "prompt_expansion": {
            "default": false,
            "description": "Whether to expand the prompt for better results.",
            "type": "boolean",
            "x-ui-component": "switch"
          }
        },
        "required": [
          "model",
          "prompt",
          "resolution",
          "duration",
          "refers"
        ],
        "type": "object",
        "x-order-properties": [
          "model",
          "prompt",
          "refers",
          "resolution",
          "duration",
          "ratio",
          "prompt_expansion"
        ]
      },
      "PredictionResponse": {
        "properties": {
          "created_at": {
            "description": "ISO timestamp of when the request was created (e.g., “2023-04-01T12:34:56.789Z”).",
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for the prediction, the ID of the prediction to get.",
            "type": "string"
          },
          "model": {
            "description": "Model ID used for the prediction.",
            "type": "string"
          },
          "outputs": {
            "description": "Array of URLs to the generated content (empty when status is not completed).",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "status": {
            "description": "Status of the task: created, processing, completed, or failed.",
            "type": "string"
          },
          "urls": {
            "description": "Object containing related API endpoints.",
            "type": "object"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "in": "header",
        "name": "Authorization",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "description": "The AtlasCloud API.",
    "title": "AtlasCloud API",
    "version": "1.0.0"
  },
  "openapi": "3.0.0",
  "paths": {
    "/api/v1/model/prediction/{request_id}": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "request_id",
            "required": true,
            "schema": {
              "description": "Request ID",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PredictionResponse"
                }
              }
            },
            "description": "Result of the request."
          }
        }
      },
      "x-api-name": "model_result"
    },
    "/api/v1/model/generateVideo": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Input"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PredictionResponse"
                }
              }
            },
            "description": "The request status."
          }
        }
      },
      "x-api-name": "model_run"
    }
  },
  "servers": [
    {
      "url": "https://api.atlascloud.ai"
    }
  ]
}

LLM 친화적 프롬프트 템플릿

# minimax/h3-developer/reference-to-video

> MiniMax H3-Developer self-hosted reference-to-video: generate a video that keeps the subject from one or more reference images/videos, driven by a text prompt, with generated audio. Supports 480P768P/2K.


## Overview

- **Submit endpoint (POST)**: `https://api.atlascloud.ai/api/v1/model/generateVideo` — start an async generation; returns a `prediction_id`
- **Poll endpoint (GET)**: `https://api.atlascloud.ai/api/v1/model/prediction/{prediction_id}` — poll this until the prediction finishes
- **Model ID**: `minimax/h3-developer/reference-to-video`


## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
See the input and output schema below, as well as the usage examples.


### Input Schema

The API accepts the following input parameters:

- **`model`** (`string`, _required_):
  model name
  - Default: `"minimax/h3-developer/reference-to-video"`

- **`prompt`** (`string`, _required_):
  The text prompt describing the video to generate.

- **`refers`** (`array[object]`, _required_):
  Reference materials that anchor the generation. Any mix of reference images, videos, and audio, each as a public URL. At least one image OR video is required (audio alone is not allowed). Image formats: png, jpeg, jpg, webp; video: mp4, mov; audio: mp3, wav. 'type' is optional — when omitted it is inferred from the URL extension.
  - Min items: 1
  - Item properties:
    - **`url`** (`string`, _required_):
      Public URL of the reference image / video / audio.

    - **`type`** (`string`, _optional_):
      Media kind. Optional; inferred from the URL when omitted.
      - Options: "image", "video", "audio"


- **`resolution`** (`string`, _required_):
  The resolution of the generated video.
  - Default: `"768P"`
  - Options: "480P", "768P", "1440p-sr", "4k-sr"

- **`duration`** (`number`, _required_):
  The duration of the generated video in seconds.
  - Default: `8`
  - Options: 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

- **`ratio`** (`string`, _optional_):
  The aspect ratio of the generated video. Use 'adaptive' to let the model choose.
  - Default: `"adaptive"`
  - Options: "adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16"

- **`prompt_expansion`** (`boolean`, _optional_):
  Whether to expand the prompt for better results.
  - Default: `false`



**Required Parameters Example**:

```json
{
  "model": "minimax/h3-developer/reference-to-video",
  "prompt": "",
  "resolution": "768P",
  "duration": 8,
  "refers": [
    {
      "url": "",
      "type": "image"
    }
  ]
}
```


**Full Example**:

```json
{
  "model": "minimax/h3-developer/reference-to-video",
  "prompt": "",
  "refers": [
    {
      "url": "",
      "type": "image"
    }
  ],
  "resolution": "768P",
  "duration": 8,
  "ratio": "adaptive",
  "prompt_expansion": false
}
```


### Output Schema

The API returns the following output format:


- **`created_at`** (`string`, _optional_):
  ISO timestamp of when the request was created (e.g., “2023-04-01T12:34:56.789Z”).

- **`id`** (`string`, _optional_):
  Unique identifier for the prediction, the ID of the prediction to get.

- **`model`** (`string`, _optional_):
  Model ID used for the prediction.

- **`outputs`** (`array[string]`, _optional_):
  Array of URLs to the generated content (empty when status is not completed).

- **`status`** (`string`, _optional_):
  Status of the task: created, processing, completed, or failed.

- **`urls`** (`object`, _optional_):
  Object containing related API endpoints.



**Example Response**:

```json
{
  "created_at": "",
  "id": "",
  "model": "",
  "outputs": [
    ""
  ],
  "status": "",
  "urls": {}
}
```


## Usage Examples

### cURL

```bash
# Step 1: Start generation (async)
curl -X POST "https://api.atlascloud.ai/api/v1/model/generateVideo" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax/h3-developer/reference-to-video",
  "prompt": "",
  "refers": [
    {
      "url": "",
      "type": "image"
    }
  ],
  "resolution": "768P",
  "duration": 8,
  "ratio": "adaptive",
  "prompt_expansion": false
}'

# Response will contain: {"code": 200, "data": {"id": "prediction_id", "status": "processing"}}

# Step 2: Poll for result (replace {prediction_id} with the id returned above)
curl -X GET "https://api.atlascloud.ai/api/v1/model/prediction/{prediction_id}" \
  -H "Authorization: Bearer $ATLASCLOUD_API_KEY"

# Keep polling until status is "completed", "succeeded" or "failed"
# When completed, outputs will contain the generated content URL(s)
```

## Additional Resources

### Documentation

- [Model Playground](https://www.atlascloud.ai/models/minimax/h3-developer/reference-to-video)

The race car driver raises a hand in celebration of the victory.

로드 중...

MiniMax H3-Developer Reference-to-Video

MiniMax H3-Developer Reference-to-Video keeps a subject consistent — with sound. Provide one or more reference materials (images and/or videos of a person, animal, or object) plus a prompt. Generate native 480P or 768P video, or select an ESR tier to enhance the output to a 1080P, 1440P, or 4K short edge while preserving the referenced subject's identity, complete with a synchronized soundtrack generated from the described scene.

Why Choose This?

Subject-consistent generation Keep the referenced subject's identity across the whole shot.
Multi-modal references Drive generation with images and/or videos in a single request.
Native audio A matching soundtrack is generated alongside the video — no separate audio input needed.
Enhanced resolution output Generate native 480P or 768P video, or use ESR for a 1080P, 1440P, or 4K short edge.
Selectable duration Produce 5–15s clips.

Parameters

Parameter	Required	Description
prompt	No	Text description of the desired video while keeping the referenced subject's identity
refers	Yes	Array of reference materials. Each item is an object `{ "url": string, "type": "image" \| "video" \| "audio" }`. `type` is inferred from the URL extension when omitted. At least one image or video is required; audio alone is rejected
resolution	No	Video resolution. Available options: `768P` (default), `480P`, `1080p-esr`, `1440p-esr`, `4k-esr`. ESR tiers generate a native 768P source and enhance the output to the requested short edge.
duration	No	Duration of the generated video in seconds. Integer between 5 and 15 (default 5)
prompt_expansion	No	Enable AI prompt expansion via H3 Context-IR. When `true`, your prompt is first expanded into a rich, structured description (shot, soundscape, music) before generation, and an additional per-token Context-IR fee applies. Default `false`: the prompt is used as-is with no extra charge.

How to Use

Add your reference materials — pass one or more refers entries (image and/or video URLs).
Write your prompt — describe the desired scene, action, and sound while keeping the subject.
Set resolution and duration — balance quality against generation speed.
(Optional) Tune seed and steps — fix the seed for reproducibility, raise steps for quality.
Run — submit and download your video.

Best Use Cases

Character Consistency — Keep the same character across multiple shots.
Product Showcases — Feature a specific product while varying the scene.
Brand & IP — Reuse a mascot or signature subject in new content.
Storytelling — Build a narrative around a consistent subject, with matching sound.

Pro Tips

Use clear, high-quality reference images or videos of the subject.
Provide at least one image or video reference; audio-only requests are rejected.
Describe the scene's audio (traffic, music, crowd) to shape the generated soundtrack.
Keep the prompt focused on the scene and action; the subject's identity comes from the references.

Notes

At least one image or video reference is required.
The prompt is optional but strongly recommended.
ESR tiers add an enhancement stage after native generation and may take longer than native resolutions.
Ensure all reference URLs are publicly accessible.
Generation is asynchronous — submit, then poll for the finished video.