HeyGen Video Agent needs two polls. Sume's avatar video needs one

HeyGen's Video Agent flow takes two polls: one on a session until a video id appears, and a second on the video until it completes or fails. Sume's avatar talking-video route returns a single job that you poll, or that calls your webhook, until it reaches a terminal state. The trade is control: HeyGen's agent plans the video from a prompt, while Sume's route expects a ready avatar and a script.

HeyGen's steps are from its quick start, read 2026-10-10. Sume's are from the Generate avatar video and Jobs and results docs.

The two flows

The HeyGen page uses base https://api.heygen.com and an X-Api-Key header. POST /v3/video-agents with a prompt returns a session_id. You poll /v3/video-agents/{session_id} until a video_id appears, then poll /v3/videos/{video_id} until the status is completed or failed. The page suggests intervals of 5 and 10 seconds, notes that a callback_url removes the need to poll, and says failures carry a failure_code and failure_message.

Sume sends POST /v1/avatar-1.0/talking-video with an avatar_handle and either a script or ordered video_inputs. It returns the standard job envelope; you poll status_url and read result_url when result_ready is true.

What you give up and gain

A prompt-driven agent saves you from writing the script and the scene plan. That is HeyGen's advantage if you want the platform to decide the content. Sume's route needs you to bring the script, which means more work up front and more predictability. You can set scene direction as a prompt or a photo, add a product_image, or give per-scene characters inside video_inputs.

Sume's route also has hard edges worth knowing. The planned duration must be 4 to 60 seconds; make longer scripts shorter or split them across jobs. Output is 720p at this time. Avatar 1.0 speaks English only, so a Korean or Spanish script is outside what this route is meant for.

Porting the polling code

If you wrote a two-stage poller for HeyGen, you can delete the first stage. Submit with an Idempotency-Key, keep the job id, and poll GET /v1/jobs/:id/status with backoff until completed, failed or canceled. Do not re-submit the paid request because your local process timed out; the docs are explicit on that. A failed job carries its reason in the job record, in place of HeyGen's failure_code.

Choose by the work: if you need the platform to draft the video from an idea, HeyGen's agent is the one that does that. If you already have a script and an avatar and want a predictable single job, Sume's route is shorter to integrate. Run both on a real script before you commit.