上传本地参考图，下载图片与视频

Agent 可以直接上传本地 PNG/JPEG，无需外部 OSS。参考图返回可复用的资产 ID；生成结果通过短期媒体地址下载，支持断点续传。

下载 Python Agent 示例 · Python 3.10+，仅使用标准库。

H3 默认 8 步、768p；480p 与 1080p 可选，1080p 为超分输出。资产 ID 的首尾帧、多参考字段当前适用于 H3-Local；其它图片模型请按其接口使用 multipart 或已授权的图片地址。

使用 ComfyUI？下载专用节点与四个可导入工作流。

上传至 MinIO：两种入口

Python 示例默认授权直传 MinIO：Llmer 签发上传授权，Agent 自动 PUT 本地图片到 MinIO，再完成校验。文件字节不经 Llmer 应用转发。

经 Llmer 上传至 MinIO（multipart）：Agent 将 file 字段发给 /v1/assets，Llmer 写入同一 MinIO 并返回资产。此前的“普通上传”指这个接口；两种方式都无需外部 OSS。

现有 Agent 接入与工具说明

有本地文件读取和 Python/HTTP 执行能力的 Agent 可直接调用示例。固定工具列表的 Agent 需加载新定义并绑定执行器；仅配置聊天模型不会自动获得上传下载能力。

完整调用契约、迁移步骤与工具绑定 · 函数工具定义 JSON

Agent 自动读取用户附件、上传取得资产 ID、按授权提交任务、查询并下载；用户无需手动复制 OSS 链接。工具 JSON 需宿主注册和执行，不是 MCP 服务地址。

1．设置连接

export LLMER_BASE_URL=https://ry.live
# 将自己的 API 密钥放入 LLMER_API_KEY 环境变量，不要写入脚本或公开日志。
python3 llmer_media.py upload ./reference.png

上传返回 id、sha256、size_bytes 和 expires_at。每张不超过 10 MiB、16 百万像素；H3 合计不超过 20 MiB。参考资产有效期 24 小时，提交前需有效；模型已接收的任务使用已解析图片，不依赖短期下载链接。

2．准备首尾帧请求

python3 llmer_media.py prepare \
  --prompt "固定机位，主体自然转动，保持外观一致" \
  --first-frame ./first.png --last-frame ./last.png \
  --output request.json

prepare 只上传图片、保存请求，不运行视频生成。单首帧只传 --first-frame，单尾帧只传 --last-frame。

{
  "model": "minimax-h3-local/image-to-video",
  "prompt": "固定机位，主体自然转动，保持外观一致",
  "seconds": 5,
  "steps": 8,
  "resolution": "768P",
  "first_frame_asset_id": "asset_…",
  "last_frame_asset_id": "asset_…"
}

3．多参考图

python3 llmer_media.py prepare \
  --prompt "保持商品外观与材质，缓慢展示细节" \
  --reference ./front.png --reference ./side.png \
  --output references.json

1–4 张参考图按传入顺序保存为 reference_asset_ids。多参考模式与首尾帧模式互斥，不能与 base64 / multipart 图片字段混用；旧版直接上传方式继续兼容。

4．明确提交，保存任务凭据

# 此命令会创建生成任务并按当前模型价格计费。
python3 llmer_media.py submit request.json --receipt task.json
python3 llmer_media.py status task_…

每次新任务使用新的 receipt 文件。提交超时且未取得任务 ID 时，先核对任务记录；不要自动重发生成请求。可复用已完成的资产上传。

5．下载已有任务结果

python3 llmer_media.py download task_… --output video.mp4
# 其它已有任务的图片：artifact key 从任务 artifacts 接口取得。
python3 llmer_media.py download task_… --artifact image_1 --output image.png

中断后运行相同下载命令，会使用 .part 及身份记录续传。地址过期会重新授权同一结果，不重新生成。请保留同目录的 .part.json 文件；完成后输出文件大小与 SHA-256。

自动等待与重试

上传和下载遇到 429 自动按 Retry-After 等待；未提供时默认等待 60 秒。每个可重试步骤最多尝试 5 次，超限保留状态并报错。下载失败只续签、重试同一结果并保留断点文件；生成 submit 在 429、超时等任何错误下都不会自动重发。

已有 Agent 请更新 Python 示例并重载工具；完整重试规则包含等待上限与错误处理边界。

HTTP 接口

接口	用途
`POST /v1/assets`	经 Llmer 上传至 MinIO；multipart 的 file 字段，一次返回资产
`POST /v1/assets/uploads`	直传 MinIO；用 size_bytes、mime_type 申请短期 PUT 上传会话
`POST /v1/assets/uploads/{id}/complete`	幂等校验并固化图片
`GET /v1/assets/{id}`	资产信息
`POST /v1/assets/{id}/download-url`	参考图读取地址
`POST /v1/videos/{id}/download-url`	已有视频的下载授权
`POST /v1/tasks/{id}/artifacts/{key}/download-url`	已有图片、视频等任务成品的下载授权

API 调用携带 Authorization: Bearer …。返回的媒体 URL 已含专用签名，访问它时不要再次附上 API 密钥。下载授权默认有效 15 分钟；任务成品尚在归档时，下载授权返回 202 与 Retry-After，稍后重试下载授权即可。浏览器原有预览和下载入口继续可用。

不要公开资产下载链接。未登录、跨用户或过期资产请求会被拒绝；结果保留期限仍按原有规则。

返回完整 API 文档