Muxla 文档

外观

Google Omni 接入指南 ​

Google Omni 视频生成使用 Interactions API 格式：

txt
POST https://mux.la/v1beta/interactions

模型名称请从 Muxla 控制台 的模型列表中复制。

请求头 ​

http
Content-Type: application/json
Authorization: Bearer {API_KEY}

{API_KEY} 填写你的 Muxla Token。

文生视频请求 ​

bash
curl "https://mux.la/v1beta/interactions" \
  -H "Authorization: Bearer 你的 Muxla Token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google-omni-video",
    "input": "生成一段 16:9 的科技产品发布会开场视频，镜头缓慢推进，画面干净明亮。",
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9",
      "delivery": "uri"
    }
  }'

参考图生成视频 ​

参考图可以放在 input 数组中，和文字提示词一起提交：

bash
curl "https://mux.la/v1beta/interactions" \
  -H "Authorization: Bearer 你的 Muxla Token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google-omni-video",
    "input": [
      {
        "type": "text",
        "text": "参考这张产品图，生成一段适合电商详情页首屏的视频，主体保持稳定，背景轻微运动。"
      },
      {
        "type": "image",
        "mime_type": "image/png",
        "data": "BASE64_IMAGE_DATA"
      }
    ],
    "response_format": {
      "type": "video",
      "aspect_ratio": "1:1",
      "delivery": "uri"
    }
  }'

data 填写 base64 内容，不包含 data:image/png;base64, 前缀。

连续编辑 ​

如果需要基于上一轮结果继续编辑，可以传入 previous_interaction_id：

json
{
  "model": "google-omni-video",
  "previous_interaction_id": "interaction_abc123",
  "input": "保持主体不变，把背景改成夜晚城市灯光。",
  "response_format": {
    "type": "video",
    "aspect_ratio": "16:9",
    "delivery": "uri"
  }
}

异步生成视频 ​

视频生成耗时较长时，可以设置 background: true 异步创建任务。创建请求会先返回 interaction ID，客户端随后通过该 ID 查询任务进度，无需持续等待创建请求完成。

创建异步任务 ​

bash
curl "https://mux.la/v1beta/interactions" \
  -H "Authorization: Bearer 你的 Muxla Token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google-omni-video",
    "background": true,
    "input": "生成一段 16:9 的海边日出延时视频，镜头保持稳定。",
    "response_format": {
      "type": "video",
      "aspect_ratio": "16:9",
      "delivery": "uri"
    }
  }'

从创建响应的顶层 id 获取 interaction ID。部分兼容响应也可能使用 interaction_id，或在 name 路径末尾携带 ID。

查询任务状态 ​

将 interaction ID 拼接到查询接口：

bash
curl "https://mux.la/v1beta/interactions/interaction_abc123" \
  -H "Authorization: Bearer 你的 Muxla Token"

也可以将接口写成通用形式：

txt
GET https://mux.la/v1beta/interactions/{interaction_id}

根据查询响应顶层的 status 处理任务：

  • completed：任务完成，停止轮询，并按下文“URI 返回与视频下载”读取视频结果。
  • failed、cancelled、canceled、expired：任务未成功完成，停止轮询并读取 error 或 message。
  • 其他状态：任务仍在处理，等待一段时间后再次查询。

建议使用 10 秒左右的轮询间隔，避免过于频繁地请求查询接口。

Python 完整示例 ​

安装依赖：

bash
pip install requests

设置环境变量后运行脚本：

bash
export MUXLA_API_KEY="你的 Muxla Token"
python
import json
import os
import time

import requests


base_url = "https://mux.la"
api_key = os.environ["MUXLA_API_KEY"]
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

body = {
    "model": "google-omni-video",
    "background": True,
    "input": "生成一段 16:9 的海边日出延时视频，镜头保持稳定。",
    "response_format": {
        "type": "video",
        "aspect_ratio": "16:9",
        "delivery": "uri",
    },
}

response = requests.post(
    f"{base_url}/v1beta/interactions",
    headers=headers,
    json=body,
    timeout=60,
)
response.raise_for_status()
data = response.json()

interaction_id = data.get("id") or data.get("interaction_id")
if not interaction_id and isinstance(data.get("name"), str):
    interaction_id = data["name"].rstrip("/").rsplit("/", 1)[-1]
if not interaction_id:
    raise RuntimeError("创建响应中未找到 interaction ID")

success_statuses = {"completed", "succeeded", "success", "done"}
failure_statuses = {"failed", "cancelled", "canceled", "expired"}
query_url = f"{base_url}/v1beta/interactions/{interaction_id}"

while True:
    response = requests.get(
        query_url,
        headers={"Authorization": f"Bearer {api_key}"},
        timeout=60,
    )
    response.raise_for_status()
    data = response.json()

    status = data.get("status") or data.get("state") or ""
    if isinstance(status, dict):
        status = status.get("status") or status.get("state") or ""
    status = str(status).strip().lower()

    print(f"interaction_id={interaction_id}, status={status or '<missing>'}")

    if status in success_statuses:
        print(json.dumps(data, ensure_ascii=False, indent=2))
        break

    if status in failure_statuses:
        error = data.get("error") or data.get("message") or "unknown error"
        if not isinstance(error, str):
            error = json.dumps(error, ensure_ascii=False)
        raise RuntimeError(f"视频生成失败，status={status}: {error}")

    time.sleep(10)

常用请求字段 ​

字段必填说明
model是Google Omni 视频模型名称，请从控制台复制
input是字符串提示词，或由文本、图片片段组成的数组
background否设置为 true 时异步创建任务，随后使用 interaction ID 查询进度和结果
response_format否输出格式配置，视频生成使用 type: "video"
response_format.aspect_ratio否输出宽高比，例如 "16:9"、"1:1"、"9:16"
response_format.delivery否设置为 "uri" 时，完成响应中的视频内容对象会返回 uri
previous_interaction_id否上一轮 interaction ID，用于连续编辑
generation_config否生成配置，具体支持字段以网关实际返回为准

URI 返回与视频下载 ​

设置 response_format.delivery 为 "uri" 后，任务完成时会在响应中返回视频 URI。读取结果时：

  1. 确认顶层 status 为 completed。
  2. 在 steps[] 中查找 type 为 model_output 的步骤。
  3. 在该步骤的 content[] 中查找 type 为 video 的对象。
  4. 读取视频对象中的 mime_type 和 uri。

不同渠道返回的 URI 格式和下载方式不同。

Vertex AI 渠道 ​

Vertex AI 渠道返回 gs:// 格式的 Google Cloud Storage URI：

json
{
  "id": "interaction_vertex_example",
  "status": "completed",
  "steps": [
    {
      "content": [
        {
          "mime_type": "video/mp4",
          "uri": "gs://example-bucket/video-output/example.mp4",
          "type": "video"
        }
      ],
      "type": "model_output"
    }
  ],
  "object": "interaction",
  "model": "gemini-omni-flash-preview"
}

将完整的 gs:// URI 作为 uri 查询参数传给 Muxla GCS 文件接口即可下载。建议使用 --data-urlencode 对 URI 进行编码：

bash
curl -L --get "https://mux.la/v1beta/files/gcs" \
  -H "Authorization: Bearer 你的 Muxla Token" \
  --data-urlencode "uri=gs://example-bucket/video-output/example.mp4" \
  --output output.mp4

AI Studio 渠道 ​

AI Studio 渠道返回 Google Generative Language 文件下载 URI：

json
{
  "id": "interaction_ai_studio_example",
  "status": "completed",
  "steps": [
    {
      "content": [
        {
          "mime_type": "video/mp4",
          "uri": "https://generativelanguage.googleapis.com/v1beta/files/example-file-id:download?alt=media",
          "type": "video"
        }
      ],
      "type": "model_output"
    }
  ],
  "object": "interaction",
  "model": "gemini-omni-flash-preview"
}

下载时保持 URI 的路径和查询参数不变，将域名替换为 mux.la：

bash
curl -L "https://mux.la/v1beta/files/example-file-id:download?alt=media" \
  -H "Authorization: Bearer 你的 Muxla Token" \
  --output output.mp4

SDK 中可能存在 output_video 等便利字段；HTTP REST 文档以 steps[].content[] 中的原始响应结构为准。