开发者 API 文档

export MONTAGEA_API_BASE="https://api.montagea.com/api/v1"
export MONTAGEA_API_KEY="mtg_..."

文本

模型：qwen-27b。支持 system/developer/user/assistant/tool 消息、文本块数组及用户消息中的 image_url。总上下文为 32,768 token，包含消息、工具定义、Schema 指令、图片和预留输出；完整输入另有 64,000 字符限制（不含图片数据）。最多 10 张 PNG/JPEG/WebP，单张 20 MiB、合计 64 MiB；审核与推理前统一缩放至最长边 1024 像素。非流式最多输出 2,048 token，流式最多 8,192 token。按模型实际用量结算，退回未使用的预留额度。

图片

模型:qwen-image(1K/2K,最多 8 张参考图)和 z-image(1K,仅文生图)。每次请求的张数 n:qwen-image 1K 最多 6 张(带参考图最多 4 张),2K 每次 1 张;z-image 最多 8 张;同时不超过账号的同时出图上限。提示词最多 5,500 字符。比例:1:1、16:9、9:16、4:3、3:4、3:2、2:3。可选 seed:0–2147483647;批量逐张递增,超出后回到 0。批量部分成功时只收取已交付图片的费用。

视频

模型：minimax-h3。支持文生视频、首尾帧或参考媒体；720p，4–15 秒。可选 seed：0–2147483647。比例：16:9、9:16、1:1、4:3、3:4、21:9；auto 需要视觉输入。每 5 秒轮询返回的 ID。视频自带生成声音，参考音频不保证口型同步。不调用外部托管模型，不自动重新提交生成。

文本

curl "$MONTAGEA_API_BASE/chat/completions" \
  -H "Authorization: Bearer $MONTAGEA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: chat-example-1' \
  -d '{"model":"qwen-27b","messages":[{"role":"user","content":"Describe a quiet mountain lake."}],"max_tokens":1024}'

{
  "id": "req_8c41d2",
  "object": "chat.completion",
  "created": 1793102400,
  "model": "qwen-27b",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "The lake lies perfectly still..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 18, "completion_tokens": 96, "total_tokens": 114 },
  "montagea_usage": { "credits": 1 }
}

图片

curl "$MONTAGEA_API_BASE/images/generations" \
  -H "Authorization: Bearer $MONTAGEA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-example-1' \
  -d '{"model":"qwen-image","prompt":"A quiet mountain lake at sunrise","resolution":"1K","aspect_ratio":"16:9","n":1}'

{
  "id": "req_5b07e9",
  "created": 1793102400,
  "data": [{ "url": "https://.../req_5b07e9.png" }],
  "montagea_usage": { "credits": 20 }
}

视频

curl "$MONTAGEA_API_BASE/videos" \
  -H "Authorization: Bearer $MONTAGEA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: video-example-1' \
  -d '{"model":"minimax-h3","prompt":"A quiet mountain lake at sunrise","seconds":5,"resolution":"720p","aspect_ratio":"16:9"}'

# Poll every 5 seconds with the returned id
curl "$MONTAGEA_API_BASE/videos/req_3f2a9c" \
  -H "Authorization: Bearer $MONTAGEA_API_KEY"

// POST /videos -> 202
{
  "id": "req_3f2a9c",
  "model": "minimax-h3",
  "object": "video",
  "kind": "video",
  "status": "in_progress",
  "created_at": 1793102400,
  "progress": 0,
  "seconds": "5",
  "size": "1344x768",
  "result": null,
  "error": null,
  "usage": { "credits": 0, "cost_nano_usd": null, "reserved_credits": 120 }
}

// GET /videos/req_3f2a9c once finished
{
  "id": "req_3f2a9c",
  "status": "completed",
  "result": { "url": "https://.../req_3f2a9c.mp4", "seconds": 5 },
  "error": null,
  "usage": { "credits": 120, "cost_nano_usd": null, "reserved_credits": 0 },
  ...
}

curl "$MONTAGEA_API_BASE/images/edits" \
  -H "Authorization: Bearer $MONTAGEA_API_KEY" \
  -H 'Idempotency-Key: edit-example-2' \
  -F 'model=qwen-image' \
  -F 'prompt=Change the background to a sunny garden' \
  -F '[email protected]' \
  -F 'resolution=1K' \
  -F 'seed=42'

// POST /videos (JSON): first/last frames
{
  "model": "minimax-h3", "prompt": "A person turns toward the camera",
  "start_frame_url": "https://your-storage.example/start.png",
  "end_frame_url": "https://your-storage.example/end.png",
  "seconds": 5, "seed": 42
}

// POST /videos (JSON): reference media, without first/last frames
{
  "model": "minimax-h3", "prompt": "The person walks through the garden",
  "reference_image_urls": ["https://your-storage.example/person.png"],
  "reference_video_urls": ["https://your-storage.example/motion.mp4"],
  "reference_audio_urls": ["https://your-storage.example/voice.wav"],
  "seconds": 5, "seed": 42
}

from openai import OpenAI

client = OpenAI(base_url="https://api.montagea.com/api/v1", api_key="mtg_...")

reply = client.chat.completions.create(
    model="qwen-27b",
    messages=[{"role": "user", "content": "Describe a quiet mountain lake."}],
    max_tokens=1024,
    extra_headers={"Idempotency-Key": "chat-example-2"},
)
print(reply.choices[0].message.content)

image = client.images.generate(
    model="qwen-image",
    prompt="A quiet mountain lake at sunrise",
    n=1,
    extra_body={"resolution": "1K", "aspect_ratio": "16:9"},
    extra_headers={"Idempotency-Key": "image-example-2"},
)
print(image.data[0].url)

with open("portrait.png", "rb") as reference:
    edited = client.images.edit(
        model="qwen-image",
        image=reference,
        prompt="Change the background to a sunny garden",
        extra_body={"resolution": "1K", "seed": 42},
        extra_headers={"Idempotency-Key": "edit-example-1"},
    )
print(edited.data[0].url)

encoded = client.images.generate(
    model="qwen-image", prompt="A quiet lake",
    size="1536x1024", response_format="b64_json",
    extra_headers={"Idempotency-Key": "image-base64-1"},
)
import base64
with open("lake.png", "wb") as output:
    output.write(base64.b64decode(encoded.data[0].b64_json))

video = client.videos.create_and_poll(
    model="minimax-h3", prompt="A quiet lake at sunrise",
    seconds="4", size="1280x720", poll_interval_ms=5000,
    extra_headers={"Idempotency-Key": "video-sdk-1"},
)
if video.status == "completed":
    client.videos.download_content(video.id).write_to_file("lake.mp4")
else:
    print(video.error)

# Tool calls are returned to your app; Montagea does not execute them.
reply = client.chat.completions.create(
    model="qwen-27b",
    messages=[{"role": "user", "content": "What is the weather in Paris?"}],
    tools=[{"type": "function", "function": {
        "name": "get_weather", "strict": True,
        "parameters": {
            "type": "object", "properties": {"city": {"type": "string"}},
            "required": ["city"], "additionalProperties": False,
        },
    }}],
    tool_choice="required",
)
print(reply.choices[0].message.tool_calls)

structured = client.chat.completions.create(
    model="qwen-27b",
    messages=[{"role": "user", "content": "Return the city Paris."}],
    response_format={"type": "json_schema", "json_schema": {
        "name": "city", "strict": True,
        "schema": {
            "type": "object", "properties": {"city": {"type": "string"}},
            "required": ["city"], "additionalProperties": False,
        },
    }},
)
print(structured.choices[0].message.content)

import base64
with open("portrait.png", "rb") as image:
    image_url = "data:image/png;base64," + base64.b64encode(image.read()).decode()
vision = client.chat.completions.create(
    model="qwen-27b",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Describe this picture."},
        {"type": "image_url", "image_url": {"url": image_url}},
    ]}],
)
print(vision.choices[0].message.content)

stream = client.chat.completions.create(
    model="qwen-27b",
    messages=[{"role": "user", "content": "Write a short poem about rain."}],
    max_tokens=512,
    stream=True,
    stream_options={"include_usage": True},
    extra_headers={"Idempotency-Key": "chat-stream-example-1"},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")