How to Translate a Video With Codex and HeyGen

Codex can translate an existing video with HeyGen by passing a public HTTPS video URL and one target language to the current HeyGen Video Translate Action in Aident Loadout. Inspect and preflight the Action first, approve exactly one translation, save the returned translation ID, and poll the matching status Action until it returns a completed video URL or a terminal failure.

This workflow is for product demos, tutorials, ads, interviews, and other finished videos whose speech needs a new language. It preserves the original visual track by default while HeyGen translates the speech, clones voices, and synchronizes lip movement. It does not rewrite the script, edit scenes, or choose whether the translation is culturally appropriate for you.

What You Need

Prepare these inputs before asking Codex to run anything:

• a source video at a publicly accessible HTTPS URL;

• the exact target language name accepted by HeyGen;

• the number of speakers when you know it;

• a short title that identifies the source and target language;

• a decision on whether to translate only the audio or produce the full lip-synced video.

Do not put an API key, signed internal URL, customer secret, or private storage credential in the prompt. Aident Loadout supplies the managed HeyGen connection. The source URL still needs to be fetchable by HeyGen, so use an approved storage location and remove public access after the translation is safely stored.

Set Up Aident Loadout in Codex

Give Codex the canonical setup instruction:

Follow https://aident.ai/SETUP.md

Then ask it to verify account and Vault status, search the staging capability catalog for the public HeyGen Video Translate Action, and inspect the current schema. Do not copy an internal capability identifier from this guide. Catalog versions and provider contracts can change, while discovery gives Codex the live Action available to your account.

The Action inspected on August 7, 2026 required two fields:

It also exposed optional title, speaker_num, and translate_audio_only fields. Inspect the schema again before each new automation instead of assuming these fields remain unchanged.

Preflight Before Translation

Preflight is the point where Codex validates the request and shows the exact Aident credit estimate without dispatching HeyGen. The current Action quoted 50 Loadout credits for one translation when checked on August 7, 2026. Treat that as a dated observation, not a permanent price.

Use a prompt like this:

Check Aident Loadout account authentication and Vault status.
Search the staging catalog for the public HeyGen Video Translate Action.
Inspect its current schema and preflight this request without executing it:

- source video: https://media.example.com/product-demo.mp4
- output language: Spanish (Spain)
- title: Product demo - Spanish
- speakers: 2
- translate audio only: false

Return the normalized inputs, operation risk, and exact credit estimate.
Do not start the translation until I approve that exact request

A valid preflight should confirm the required fields and return a bounded quote. Stop if the URL is private, the language is rejected, the quote is unavailable, the schema differs from the prompt, or the Action requests an unexpected credential.

Submit Exactly One Translation

After reviewing the quote and source rights, approve one execution:

Execute the exact preflighted HeyGen translation once.
Do not change the source URL, language, speaker count, title, or audio-only setting.
Record the returned translation ID and raw status before doing anything else.
Do not submit a second translation if the first response is slow or ambiguous

The create request is asynchronous. A successful response means HeyGen accepted the job, not that the final video is ready. Save the translation ID because the status check uses it to distinguish this job from any other translation.

The current direct HeyGen v3 API can accept more than one output language in a request. The Aident Action inspected for this guide accepts one output_language per execution. Follow the Action schema you actually discovered and quote each additional execution separately.

Poll the Translation Status

Ask Codex to discover and inspect the corresponding HeyGen status Action rather than guessing an endpoint:

Find the read-only HeyGen Action that checks a video translation by ID.
Inspect its schema, then poll the recorded translation ID at moderate intervals.
Stop when the status is complete or failed, or when 30 minutes have elapsed.
On success, return the output language and final video URL.
On failure, return the failure message and do not create another translation

Polling every few seconds adds load without making the render finish sooner. A moderate interval and a bounded deadline keep the workflow observable. If the deadline expires while the job is still processing, keep the ID and resume status checks later. Do not turn a timeout into a duplicate write.

Expected success has four observable facts:

1. the create Action ran exactly once;

2. a translation ID was retained;

3. the status Action reached a completed state for that same ID;

4. the returned video URL plays the requested language.

Review Before You Ship the Translation

Machine translation needs editorial review even when the request succeeds. Check the entire output with a fluent reviewer or qualified localization vendor when the video affects customers, safety, legal terms, pricing, or brand claims.

Review at least these points:

• names, product terms, acronyms, numbers, dates, and calls to action;

• speaker separation and whether each translated voice stays with the right person;

• lip synchronization at fast speech, interruptions, and close-up shots;

• music, sound effects, and original audio that should not have been replaced;

• subtitles, on-screen text, and screenshots, which are not automatically localized by an audio translation;

• the beginning and end of the file for clipped words or extra silence.

If only the audio should change, set translate_audio_only during preflight and confirm the final visual track remains unchanged. If the video itself needs new titles, screenshots, or layouts, use a separate editing workflow after the translation is approved.

Common Failures

HeyGen Cannot Fetch the Source URL

Open the URL in a private browser session and confirm it returns the media bytes without a login, cookie, VPN, or referrer requirement. Use HTTPS and a provider-supported video format. Do not solve the problem by making an entire private bucket public.

The Output Language Is Rejected

Use HeyGen's current supported-language list and copy the accepted display name exactly. Do not convert a language name into a locale code unless the discovered Action schema asks for one.

The Job Stays in Processing

Keep the translation ID, wait, and query status later. Check HeyGen service health if the delay is unusual. Do not resubmit just because a client request timed out after the create call may have succeeded.

The Wrong Voice Speaks a Segment

If the source contains multiple speakers, preflight again with the known speaker count. For overlapping speech or many brief speakers, a manual proofread or source edit may be safer than repeated paid translations.

The Result Is Complete but the URL Later Expires

Copy the approved output into your durable storage while the delivery URL works. Store the translation ID alongside the durable asset so the job can be audited without treating a temporary delivery URL as permanent.

When to Use a Different Video Workflow

Use this translation path when the source video is already finished and the main change is spoken language. Use HeyGen Video Agent, HyperFrames, or the API when you still need to choose how the original video is produced. Use Claude Code and HyperFrames when the visuals, typography, timing, or code-driven motion must change. Use Codex and Fal when the task is generating a new clip rather than localizing an existing one.

The distinction prevents an expensive category error: translation should not become a full video-generation job, and a translated soundtrack should not be mistaken for complete visual localization.

Run the Workflow With a Measurable Gate

Give Codex one final, bounded instruction:

Follow https://aident.ai/SETUP.md
Discover and inspect the current public HeyGen video-translation and status Actions.
Preflight one translation of my public HTTPS source into my named language.
Show the exact normalized request and credit quote before execution.
After I approve, dispatch exactly once, retain the translation ID, poll at moderate
intervals, and return the completed URL or terminal failure. Do not retry the write,
publish the result, change storage permissions, or expose credentials

Success is not merely an API response. It is one quoted and approved write, one retained translation ID, one terminal status, a playable output in the requested language, and no duplicate job.

Set up Aident Loadout and translate one video.

Sources

• HeyGen: Create Video Translation

• HeyGen: Get Video Translation

• HeyGen: List Supported Translation Languages

• HeyGen: API pricing

Refresh this guide when the Aident HeyGen Action schema or quote changes, HeyGen changes translation inputs or status states, or the supported-language contract changes.