Skip to Content
Pre-render

Pre-render

给一张图、一个声音和一段脚本，得到一段这张脸说出这段话的视频（MP4），需要的话还有字幕。凡是能用录好的视频的地方都能用：网站、课程、消息。

两种

Talking headHalf-body
画面头肩整张图原样保留——手、道具、插画都在
图片一张人脸照片任何图片；按画幅形状围绕人脸裁切（没有人脸时取中间）
画幅这张脸有的画幅：竖屏、横屏或方形竖屏（720×1248）或横屏（1248×720）
要多久通常稍等即可几分钟：每秒视频约 8.5 秒，渲染器要先启动时再加最多约 13 分钟

没有裁切设置：想自己取景，就把图片裁好再发。

在控制台里

打开 Pre-render，选图片、声音和画幅，写好 Script，按 Generate video（或 Generate half-body video）。视频在后台生成， 出现在左边的 Videos 列表里，做好后点它就能观看和下载。点一个视频，右边也会换成它当时的设置，改一改再生成就是一个新视频，原来那个不变。

用 API

你的服务器用 API key 发送 POST /v1/renders，然后查询进度，直到做好：

const API = "https://api.avatargo.ai/v1";
const headers = { authorization: `Bearer ${process.env.AVATARGO_API_KEY}`, "content-type": "application/json" };
 
const res = await fetch(`${API}/renders`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    avatarId: "av_…",                // 或 imageId（你图库里的图片），或 image（https 地址或 base64）
    voiceId: "…",                    // GET /v1/voices 里某个音色的 id
    text: "Welcome to the course. Today we start with the basics.",
  }),
});
let render = await res.json();
if (!res.ok) throw new Error(`${render.error.code}: ${render.error.message}`);
 
// queued → rendering → ready，或 failed（errorCode 说明原因）
while (render.status === "queued" || render.status === "rendering") {
  await new Promise((r) => setTimeout(r, 5000));
  render = await (await fetch(`${API}/renders/${render.id}`, { headers })).json();
}
console.log(render.status, render.videoUrl, render.subtitlesUrl);
  • 图片——三选一：avatarId（你的脸，或系统提供的脸）、imageId 或 image（PNG 或 JPEG，最大 10 MB）。
  • type——talking_head（默认）或 half_body。frame——portrait（默认）、landscape，Talking head 还可以是 square。
  • subtitles——视频旁附一个 SRT，每句一条；默认开启。
  • videoUrl 和 subtitlesUrl 一小时内有效：再查询一次这个视频就能拿到新链接。视频一直保留到你删除（DELETE /v1/renders/{id}）。
  • 也可以不轮询，让 AvatarGo 通知你的服务器：render.ready 和 render.failed 两个 webhook 事件。
  • POST /v1/renders/{id}/cancel 停止一个在等待或正在渲染的视频。
  • POST /v1/renders/estimate 在生成之前告诉你一段脚本的视频会有多长。

限制

  • 脚本最多 4,000 个字符，视频最长 5 分钟——更长的脚本会在那里截断，并在 error 里说明。
  • 你的视频最多同时渲染 2 个，其余排队。每天最多 100 个。
  • 所有渲染器都忙时，视频会等一台空出来——实时通话优先——Talking head 最多等 15 分钟，Half-body 最多 30 分钟，之后以 engine_unavailable 失败。

完整的字段和错误码见 API 参考的 Pre-render 部分。

CharactersQuick start