MuxLLM
开始使用

Media API

图片与视频模型

媒体模型的能力和参数差异大于文本模型。先确认目标模型的实时端点，再选择图片、Gemini 或对应的视频任务结构。

选择媒体端点 查看模型广场

Capability Map

先区分协议与能力

场景识别依据提交路径重要边界
OpenAI 兼容图片生成image-generationPOST /v1/images/generations参数随模型变化
OpenAI 兼容图片编辑模型详情明确支持编辑POST /v1/images/edits不能从图片生成标签自动推断
Gemini 图片geminiPOST /v1beta/models/{model}:generateContent不改用图片兼容入口
视频任务 A模型详情显示 /v1/videosPOST /v1/videos按任务 ID 查询同一前缀
视频任务 B模型详情显示 /v1/video/generationsPOST /v1/video/generations按任务 ID 查询同一前缀
不要猜测openai-video 只说明视频兼容能力，不足以确定使用哪一套视频路径。必须同时查看模型详情中的实时请求入口。

Image Generation

OpenAI 兼容图片生成

仅适用于显示 image-generation 标签的模型。先发送只包含 model 和 prompt 的最小请求，再按模型说明添加尺寸、质量或其他参数。

POST /v1/images/generations
curl https://api.muxllm.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "prompt": "一张干净、现代的人工智能工作台产品图"
  }'
返回内容可能是可下载 URL 或 Base64 数据，取决于模型与渠道响应。
文件保存临时 URL 可能过期，业务需要时应在授权范围内及时下载并保存。
可选参数尺寸、质量、数量和输出格式并非所有模型通用，未知参数可能导致 400。

Image Edits

图片编辑能力需要单独确认

/v1/images/edits 路由存在，但公开模型信息没有统一的图片编辑标签。因此不能宣称所有图片模型都支持编辑；只有模型详情或已验证结果明确支持时才使用。

确认支持后的 multipart 示例
POST /v1/images/edits
curl https://api.muxllm.com/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=MODEL_NAME" \
  -F "image=@PATH_TO_IMAGE.png" \
  -F "prompt=保留主体，将背景替换为明亮的现代办公室"
上传边界上传前确认你有权处理图片，移除不必要的 EXIF 或敏感信息，并遵守目标模型对格式、大小和遮罩的要求。

Gemini Image

Gemini 图片模型使用原生协议

如果图片模型只显示 gemini 标签，应使用 generateContent。不要因为它能生成图片就改用 /v1/images/generations。

POST /v1beta/models/{model}:generateContent
curl https://api.muxllm.com/v1beta/models/MODEL_NAME:generateContent \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{ "text": "生成一张明亮、简洁的产品工作台图片。" }]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'

responseModalities 等生成参数取决于具体模型。若模型不接受该字段，应以模型详情支持的最小请求为起点调整。

Video Jobs

视频生成是异步任务

提交请求通常只会创建任务，不会立即返回成品视频。应用需要保存任务 ID、定时查询状态，并在完成后读取结果地址。

  1. 01确认入口

    从模型详情确认两套视频路径中的哪一套适用。

  2. 02提交任务

    发送模型名、提示词和该模型支持的可选参数。

  3. 03保存 ID

    持久化响应中的任务标识，避免因刷新页面丢失。

  4. 04轮询与收敛

    使用同一前缀查询，遇到终态后停止轮询。

Video Path A

/v1/videos 任务流程

仅用于模型详情明确显示该入口的模型。示例使用 multipart 提交，并通过路径参数查询任务。

POST /v1/videos
curl https://api.muxllm.com/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=MODEL_NAME" \
  -F "prompt=雨后的城市街道，镜头缓慢向前移动"
GET /v1/videos/{task_id}
curl https://api.muxllm.com/v1/videos/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Video Path B

/v1/video/generations 任务流程

仅用于模型详情明确显示该入口的模型。它与 /v1/videos 是两套独立任务前缀，不能交叉查询。

POST /v1/video/generations
curl https://api.muxllm.com/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "prompt": "雨后的城市街道，镜头缓慢向前移动"
  }'
GET /v1/video/generations/{task_id}
curl https://api.muxllm.com/v1/video/generations/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Polling

轮询任务状态

状态类别应用行为注意事项
排队 / 处理中等待后继续查询设置合理间隔和总超时，不要高频轮询
成功停止轮询并处理结果结果 URL 可能有有效期，应按业务需要及时保存
失败停止轮询并记录错误先修正参数或上游问题，不要立即无限重提
未知状态保留原始响应并谨慎重查不要把未知状态自动视为失败或重新创建任务

不同模型或渠道的状态字段和值可能不同。应用应保存原始响应，并以“处理中、成功、失败”三类业务状态做兼容映射。

Cost & Safety

提交前确认费用与内容边界

实时价格

媒体模型可能按次、尺寸、时长、清晰度或其他规格计费，不能套用文本 Token 公式。

避免重复任务

网络超时不代表任务未创建。重复提交前先查日志或任务状态，降低重复计费风险。

输入内容

只上传有权处理的图片、参考素材和提示内容，不把敏感业务文件发送给无关模型。

结果保存

下载地址可能临时有效。需要长期使用时，应在授权范围内保存并记录来源。

Troubleshooting

媒体请求错误排查

现象优先检查修正方向
不支持图片生成模型是否显示 image-generation若只显示 gemini，改用 Gemini 原生协议
图片编辑 400 / 500模型是否明确支持编辑、文件格式与参数移除可选字段，用已验证模型发送最小请求
视频提交 404选择的是哪一套视频任务前缀按模型详情切换 /v1/videos 或 /v1/video/generations
查不到任务查询前缀是否与提交前缀相同使用原任务 ID 和原路径族查询
长时间处理中上游负载、任务状态、轮询间隔延长间隔并设置总超时，不要重复创建

Before Request

先确认模型详情

媒体能力和参数变化较快，提交付费任务前应再次核对实时入口、价格与支持规格。

打开模型广场