RouterBase 媒体生成

概述

使用 routerbase 通过统一 API 访问图像、视频和音频生成模型。本能力帮助智能体选择合适的媒体端点，区分同步与异步响应，并提供面向生产环境的安全集成指引。

当需要精确的端点地址、参数说明、媒体保留策略或示例请求时，请查阅 references/routerbase-media.md。

媒体工作流

1. 确定模态类型：图像、图像编辑/放大、视频、文本转语音、音乐或其他音频。
2. 查询或确认该模态当前可用的模型 ID。若已配置凭据，优先使用实时模型目录（live catalog）。
3. 选择对应端点：
   • 图像： POST https://routerbase.com/v1/images/generations
   • 视频： POST https://routerbase.com/v1/videos/generations
   • 语音/音频： POST https://routerbase.com/v1/audio/speech 或 POST https://routerbase.com/v1/audio/generations
4. 确定同步行为：
   • 根据 RouterBase 文档，图像生成为同步操作。
   • 视频与音频生成为异步操作；需通过任务 ID 轮询任务详情，或提供 callback URL。
5. 在用户侧下载并持久化生成的文件。RouterBase 文档指出，所生成的图像/视频媒体具有时效性限制（time-limited）。
6. 为异步媒体任务添加面向用户的进度反馈与重试处理机制。

图像生成示例

curl -X POST https://routerbase.com/v1/images/generations 
  -H "Authorization: Bearer $ROUTERBASE_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "google/imagen-4",
    "prompt": "A clean product-style illustration of an AI model router dashboard",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }'

图生图示例

{
  "model": "blackforestlabs/flux-2-pro-i2i",
  "prompt": "Make the source image look like a polished watercolor editorial illustration",
  "image_urls": ["https://example.com/source.jpg"]
}

异步视频或音频调用模式

const create = await fetch("https://routerbase.com/v1/videos/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ROUTERBASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "google/veo-3-1-fast",
    prompt: "A 5-second shot of abstract network routes lighting up on a dark map",
  }),
});

const task = await create.json();
// 轮询 GET /v1/videos/generations/{id}，直至任务达到终态（terminal status）。

若应用已具备可靠的 Webhook 接收器，可直接使用 callback URL；否则，请采用带退避（backoff）机制的轮询方式，并设置明确的超时时间。

生产环境防护措施

• 确保媒体提示词（prompt）及输入图像 URL 符合用户的权限范围与产品政策要求。
• 在媒体保留期限到期前完成生成内容的本地存储。
• 根据所选模型支持的字段列表，校验 aspect_ratio、resolution、quality、style、negative_prompt 和 image_urls 等参数的有效性。
• 将模型专属参数视为模型强依赖项；不可假设所有图像模型均支持全部选项。
• 对于异步任务，需持久化保存任务 ID、请求载荷哈希值（payload hash）、创建时间、当前状态、结果 URL 及错误详情。
• 禁止将真实 API 密钥、私有媒体 URL 或用户敏感数据写入日志。

输出检查清单

• 明确说明模态类型与对应端点。
• 提供当前有效的模型 ID，或注明该 ID 需由用户自行验证。
• 说明同步/异步处理逻辑。
• 说明媒体文件的存储与保留策略。
• 提供最小可行请求示例及对应的参数校验步骤。