Skip to main content
Use v3 for new integrations. The legacy /web-app/public API remains available for existing integrations. This guide does not announce a shutdown date.

​
What changes

​
1. Set up a v3 key and wallet

Create a key in the developer console and fund the API wallet. Do not assume Studio credits or an existing subscription fund v3 requests. Keep the v3 credential in HEDRA_KEY, separate from the legacy HEDRA_API_KEY, so both integrations can run during migration. The v3 quickstart and SDK examples use HEDRA_API_KEY. Run them in a separate terminal, or pass the v3 key only to that command, for example HEDRA_API_KEY="$HEDRA_KEY" python quickstart.py or HEDRA_API_KEY="$HEDRA_KEY" npx tsx quickstart.mts after saving the quickstart examples. These command-scoped assignments leave the legacy key in your current shell unchanged.

​
2. Map each workload to a v3 model

Use the model catalog. Do not mechanically translate a v2 model slug or copy its payload: fields and capabilities differ. Read GET /v3/models/{model}/openapi.json and build the model’s input object. For example, a v3 image request uses input.prompt, rather than the legacy text_prompt field:
Check required fields, media slots, dimensions, durations, and output counts for each model. A legacy batch or inline-audio workflow may need multiple v3 jobs; do not assume a one-to-one replacement exists.

​
3. Update uploads and result handling

Upload input bytes through POST /v3/files and pass the returned URL verbatim in a reference such as {"source":"url","url":"<returned URL>"}. Use the media field advertised by the chosen model; for Veo 3 the start frame field is start_image. Re-upload if the handle has expired. Store the returned job_id, poll until COMPLETED or FAILED, then fetch GET /v3/jobs/{job_id}. Inspect each output’s status before downloading its URL. Use the server-issued outputs[].asset_id to chain jobs; never derive it from a job ID.

​
4. Validate and cut over

Test one representative input for each workload. Verify its output, cost, error handling, and file lifecycle. Confirm that every model and feature your integration needs has a supported v3 path before switching production traffic. Use webhooks or job progress for completion handling, and log drains for observability. Keep the previous integration available during your rollout. Ask Hedra engineering about unsupported workloads or account-specific migration requirements. The legacy quickstart remains available for maintaining existing integrations.