在 PHP 中渲染影片Beta

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

renderVideo 和 renderAndWaitVideo 接受範本 ID 和一個選項陣列。

渲染並等待網址

renderAndWaitVideo 會回傳 ['result' => $url] 或 ['error' => [...]]。

$result = $client->renderAndWaitVideo('tpl_xxx', [
    'modifications' => [
        ['name' => 'headline', 'text' => 'Summer sale'],
        ['name' => 'music', 'src' => 'https://example.com/song.mp3'],
    ],
]);

if (isset($result['error'])) {
    throw new RuntimeException($result['error']['message']);
}

echo $result['result'];

追蹤進度

renderVideo 會回傳事件陣列的 Generator。最後一個事件是 done 或 error。

foreach ($client->renderVideo('tpl_xxx', ['modifications' => [['name' => 'headline', 'text' => 'Summer sale']]]) as $event) {
    match ($event['type']) {
        'created' => printf("Video %s\n", $event['id']),
        'queued' => printf("%d videos before this one\n", $event['ahead']),
        'progress' => printf("%d%%\n", $event['progress'] * 100),
        'done' => print($event['url'] . "\n"),
        'error' => print($event['error']['message'] . "\n"),
    };
}

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

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

連線中斷後重新連線

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

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

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

不等待就開始影片

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

$result = $client->createVideo('tpl_xxxxxxxxx', [['name' => 'title', 'text' => 'Hi']]);

if (isset($result['error'])) {
    throw new RuntimeException($result['error']['message']);
}

echo $result['result']['id']; // vid_xxx, with the status queued

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

再次讀取影片

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

$result = $client->getVideo('vid_xxx');

if (isset($result['error'])) {
    throw new RuntimeException($result['error']['message']);
}

echo $result['result']['status'] . ' ' . ($result['result']['url'] ?? '');

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

watchVideo 會從最新的事件開始，再次產生影片的事件。它沒有 created 事件，重新連線的方式與 renderVideo 相同。

foreach ($client->watchVideo('vid_xxx') as $event) {
    if ($event['type'] === 'done') {
        echo $event['url'] . "\n";
    }
}