在 Python 中渲染影片Beta

影片範本會渲染成 MP4。影片每一秒計為一次生成，60 fps 時計為兩次。如何設計影片範本，請見生成影片。

render_video 和 render_and_wait_video 接受範本 ID 和關鍵字引數。

渲染並等待網址

render_and_wait_video 會回傳 {"result": url} 或 {"error": {...}}。

result = client.render_and_wait_video(
    "tpl_xxx",
    modifications=[
        {"name": "headline", "text": "Summer sale"},
        {"name": "music", "src": "https://example.com/song.mp3"},
    ],
)

if "error" in result:
    raise RuntimeError(result["error"]["message"])

print(result["result"])

追蹤進度

render_video 會 yield 事件的 dict。最後一個事件是 done 或 error。

for event in client.render_video("tpl_xxx", modifications=[{"name": "headline", "text": "Summer sale"}]):
    if event["type"] == "queued":
        print(f"{event['ahead']} videos before this one")
    elif event["type"] == "progress":
        print(f"{event['progress']:.0%}")
    elif event["type"] == "done":
        print(event["url"])
    elif event["type"] == "error":
        print(event["error"]["message"])

事件	欄位
created	id：影片的 ID，例如 vid_xxx
queued	ahead：排在這部影片前面的影片數量
progress	frame、totalFrames，以及從 0 到 1 的 progress
done	url：MP4 的網址
error	error：code、message 和 requestId

被拒絕的請求，例如 API 金鑰無效或配額用完，會產生一個 error 事件。影片可能要排隊好幾分鐘，因此用戶端的逾時時間只適用於連線。

連線中斷後重新連線

即使連線中斷，影片仍會渲染到完成。接著 render_video 會用 created 事件中的 ID 再次讀取同一部影片，並繼續 yield 事件。它不會再次傳送渲染請求，所以你不會為第二部影片付費。

嘗試	嘗試前的等待時間
1	1 秒
2	2 秒
3	4 秒
4	8 秒

嘗試次數用完，或連線在 created 事件之前中斷時，最後一個事件會是代碼為 TIMEOUT_ERROR 的 error。render_and_wait_video 以相同方式重新連線。

不等待就開始影片

create_video 會開始影片，並立即回傳它的 ID，不會等待渲染完成。接著用 get_video 或 watch_video 讀取影片。

result = client.create_video("tpl_xxxxxxxxx", modifications=[{"name": "title", "text": "Hi"}])

if "error" in result:
    raise RuntimeError(result["error"]["message"])

print(result["result"]["id"])  # vid_xxx, with the status queued

create_video 只會傳送一次渲染請求。再請求一次，就會渲染第二部影片。

再次讀取影片

請保留 created 事件中的 ID。get_video 會回傳影片的狀態，影片完成後也會回傳它的網址。

result = client.get_video("vid_xxx")

if "error" in result:
    raise RuntimeError(result["error"]["message"])

video = result["result"]
print(video["status"], video.get("url"))

status 是 queued、rendering、done 或 failed。失敗的影片有一個 error 字串。未知的 ID 會得到代碼為 NOT_FOUND 的錯誤。

watch_video 會從最新的事件開始，再次 yield 影片的事件。它沒有 created 事件，重新連線的方式與 render_video 相同。

for event in client.watch_video("vid_xxx"):
    if event["type"] == "done":
        print(event["url"])