Blog

Tutorial

veo-3.1/image-to-video via the HiAPI API: curl and Python tutorial

Nov 12, 2026 13 min read
Cover image: layers of bone-white paper stacked out of alignment, with a rust-red separator sheet sandwiched in the middle, casting a flat, straight shadow.
On this page

What the veo-3.1 image-to-video endpoint expects

Before you write a single line of code, it helps to be clear about what kind of call this is. veo-3.1/image-to-video does not return a video in the same HTTP response that you send your prompt in. It is an asynchronous job endpoint: you describe the video you want, the platform accepts the work, and you then check back for the result.

Conceptually, a request has two distinct halves:

  • The first-frame image. This is the still image the generated video starts from. It anchors the composition, subject, and look of the opening moment. Everything after that is generated by the model from that starting point.
  • The generation options. These are the knobs that control how the video is produced — things like whether audio should be generated, the output resolution, and how long the clip should be.

That split matters for two reasons. First, it keeps failures easy to reason about: an image problem looks different from a parameter problem, and you want to be able to tell them apart. Second, it means your code should be organized the same way — one piece of logic that prepares the image, and another that builds the option set.

What the caller must supply, at a minimum, is a valid first-frame image plus the decisions about audio, resolution, and duration. Everything else — submitting the job, tracking its status, and returning the finished video — is handled by the platform's job lifecycle. Your integration only needs to do three things: send a well-formed request, remember the job identifier you get back, and poll until the job reaches a terminal state.

One practical note before moving on: because the call is asynchronous, your code cannot assume a video is available immediately after submission. Design the flow around that from the start, and the rest of the tutorial will feel straightforward.

The two-part mental model

Keep this framing as you read the following sections:

  1. Input → the first-frame image, prepared and validated.
  2. Options → audio, resolution, duration.
  3. Job → submit, receive an identifier, poll, retrieve.

Each section below maps to one of those boxes.

Prepare the first-frame image

The first-frame image is the single most important input in an image-to-video call, so give it a dedicated step in your pipeline rather than burying it inside the request builder. The API call has to be able to reference the image, which means the image must be in a form the platform can accept and read.

What to check before sending

  • The image actually opens. A truncated download or a corrupted file is the most common cause of a confusing failure downstream. Verify it decodes cleanly before you send anything.
  • The format is one the platform accepts. If your source is a screenshot, a phone photo, or an export from a design tool, normalize it to a widely supported format before uploading. Converting once up front is cheaper than debugging later.
  • The dimensions are sane. Extremely small or extremely stretched images give the model very little to work with. If your source is tiny, consider upscaling or choosing a better frame.
  • The composition is a good starting point. Because this is the first frame, the generated motion continues from it. Choose a frame whose subject is clearly visible and whose framing you are happy to see at the start of the clip.

Keep it separate from the options

Structure your code so the image preparation returns a reference you can hand to the request builder, rather than mixing image handling with parameter assembly. Concretely:

# Pseudocode-shaped structure, not a full client
def prepare_first_frame(path):
    image = load_and_validate(path)   # decode, check format, check dimensions
    ref = upload_or_encode(image)     # produce something the API call can reference
    return ref

def build_request(first_frame_ref, options):
    return {
        "first_frame": first_frame_ref,
        # audio / resolution / duration go here
    }

This separation pays off during debugging. If a job fails, you can re-run prepare_first_frame alone and confirm the image side is healthy before touching any generation parameters.

Validate early, fail loudly

Do the validation on your side and raise a clear error when it fails. An image that is the wrong format or unreadable should never reach the network — catching it locally turns a vague async job failure into a precise, immediate exception with a message you wrote yourself.

Set generation options: audio, resolution, and duration

With the image handled, the remaining decisions are the generation options. These change the character of the output, so treat them as explicit, named parameters rather than magic values buried in the request body.

Audio

The audio option controls whether the generated video includes an audio track. Think about this as a product decision as much as a technical one:

  • If the video will be embedded silently — a background loop, an autoplaying hero — you generally do not need audio, and leaving it out keeps the output simpler to handle downstream.
  • If the clip is meant to stand alone with sound — a short social piece, a demo — enable audio so you get a complete asset from a single call.

Decide this deliberately per use case rather than defaulting blindly; it affects both the output and how your downstream pipeline treats the file.

Resolution

Resolution determines the pixel dimensions of the finished video. Choose it based on where the video will be displayed and how much detail the content needs, not simply "the biggest available." A clip rendered for a small embedded player does not benefit from being produced at a size far beyond what the display surface can show. Where the platform publishes a set of supported values, pick from that set explicitly and validate against it in your client so an unsupported value fails fast.

Duration

Duration sets how long the generated clip runs. It interacts with your content plan: a scene that needs to establish a location and then show motion needs more time than a single gesture. Note that this is one of the parameters most likely to be metered — the platform's billing is described in terms of generated output, so be conscious of how long your clips are when you batch requests.

Assemble options as one object

Keep all three together in a single options structure so there is exactly one place to look and one place to change them:

options = {
    "audio": True,          # generate an audio track
    "resolution": "...",    # one of the supported values
    "duration": 8,          # seconds of generated video
}

Use the values your account and the current endpoint documentation list as supported — read them from the documentation rather than hard-coding guesses, and check them at request-build time so a bad value never becomes a failed job.

Submit the job with curl

Now put the two halves together and submit. Start from the command line, because curl makes the request shape visible and gives you a fast way to test changes before you commit them to code.

The request

A submission looks like this in structure — replace the placeholder values with your own credentials, image reference, and option values:

curl -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_frame": "<image reference from your upload step>",
    "audio": true,
    "resolution": "<supported value>",
    "duration": 8
  }'

A few conventions worth adopting:

  • Keep the key in an environment variable ($HIAPI_API_KEY) rather than pasting it into the command. That habit carries straight over into your Python code and keeps secrets out of shell history.
  • Send JSON with an explicit Content-Type header.
  • Separate the image reference from the numeric and boolean options in the body, mirroring the two-part model from the first section.

Reading the response

Because this is an async endpoint, the successful response is not the video. It is an acknowledgement that the job was accepted, and it carries the information you need to track it — most importantly a job identifier, and typically a status field indicating that the job is queued or running.

Read it in two steps. First, confirm the HTTP status indicates acceptance rather than a client error. Second, parse the body and extract the job identifier:

curl -s -X POST "https://api.hiapi.ai/v1/veo-3.1/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | tee submit.json

Writing the response to submit.json gives you something to inspect and to feed into the polling step. If the submission fails, the error body is your first and best clue — check whether it points at the image reference or at one of the options, then fix that half in isolation and resubmit.

Poll the async job until the video is ready

Once you hold a job identifier, the workflow becomes a loop: ask the platform for the job's status, and stop when the job reaches a terminal state.

The lifecycle

An image-to-video job passes through a small set of states. It is accepted and queued, then it is being processed, and finally it either succeeds and produces a video or fails with an error. Your polling code only needs to distinguish three things:

  • Still working — keep waiting.
  • Succeeded — read the output location and download or store the video.
  • Failed — stop and surface the error.

Poll responsibly

Two habits make polling robust:

  1. Wait between checks. Hammering the status endpoint in a tight loop wastes requests and gains you nothing; generation takes real time. Use a fixed interval or a gentle backoff.
  2. Set a deadline. Never poll forever. Pick a maximum number of attempts or a maximum elapsed time, and treat exceeding it as a failure you can report clearly.
# Poll loop sketch
for i in $(seq 1 60); do
  status=$(curl -s "https://api.hiapi.ai/v1/jobs/<job_id>" \
    -H "Authorization: Bearer $HIAPI_API_KEY")
  echo "$status"
  # break when the status field reports success or failure
  sleep 5
done

Treat the exact status strings and endpoint path as things to confirm against the current API documentation rather than assumptions baked into your script.

On success

When the job reports success, the response carries the location of the finished video. Download it promptly and store it somewhere durable — job results on any asynchronous platform should be treated as something to retrieve now rather than something to fetch lazily much later. Record the job identifier alongside the stored file so you can trace any output back to the request that produced it.

The same request in Python

The Python version should not be a second implementation — it should be the same request, expressed once and reused. The goal is a single function that submits and polls, built from the same image reference and the same options object you validated earlier.

One request body, one client

import os
import time
import requests

BASE = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]

session = requests.Session()
session.headers.update({
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
})

def build_body(first_frame_ref, options):
    return {"first_frame": first_frame_ref, **options}

def submit(body):
    r = session.post(f"{BASE}/veo-3.1/image-to-video", json=body, timeout=60)
    r.raise_for_status()
    data = r.json()
    return data["job_id"]

def poll(job_id, interval=5, max_attempts=60):
    for _ in range(max_attempts):
        r = session.get(f"{BASE}/jobs/{job_id}", timeout=30)
        r.raise_for_status()
        data = r.json()
        state = data.get("status")
        if state in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} did not finish in time")

def image_to_video(first_frame_ref, options):
    job_id = submit(build_body(first_frame_ref, options))
    result = poll(job_id)
    if result["status"] == "failed":
        raise RuntimeError(result.get("error", "job failed"))
    return result  # contains the finished video location

Why this shape

  • One Session. Reusing a session keeps the auth header in one place and reuses connections across the submit and every poll.
  • One build_body. The curl request and the Python request are the same body — same keys, same values. When you change an option, you change it in one place.
  • Explicit timeouts and a deadline. Both calls set timeouts, and poll has an attempt limit, so a stalled job can never hang your process.
  • Failures are loud. raise_for_status on submission catches request-level errors immediately; the explicit failure branch in image_to_video catches job-level failures.

If you later need to call other models through the same platform, this structure generalizes: the session, the submit helper, and the poll helper stay, and only the endpoint and body builder change.

Troubleshooting a failed image-to-video call

When a call does not produce a video, narrow it down by asking which stage failed. The two-part request model gives you a clean checklist.

Stage 1: submission rejected

If the submit call itself returns an error, nothing was generated — and that is good news, because the problem is in the request.

  • Image reference problems. The single most common cause. Re-run your image preparation step alone and confirm it produces a valid, readable, correctly formatted image and a reference the API accepts. Check for truncated uploads and unsupported formats first.
  • Invalid option values. An unsupported resolution or an out-of-range duration will be rejected at submission. Validate options against the documented supported values before sending.
  • Auth and headers. Confirm the key is actually being sent (Authorization: Bearer ...) and that the body is sent as JSON. An empty or malformed body is easy to miss when building requests by hand in curl.

Stage 2: job submitted but failed

If submission was accepted but polling ends in failure, the request was well-formed and the problem is in the content or the job itself.

  • Read the job error. The failure response explains what went wrong far better than guessing. Log it verbatim.
  • Look at the first frame. A source image with no clear subject, extreme cropping, or heavy distortion gives the model little to work with. Swap in a cleaner frame and retry.
  • Reconsider the options. Very long durations or unusual combinations of settings are worth retesting with a simpler configuration to isolate which parameter is implicated.

Stage 3: polling never finishes

If your loop times out rather than failing, treat it as an infrastructure question, not a content one. Confirm you are polling the right job identifier, that your interval is not too aggressive, and that your deadline is long enough for the duration you requested. Record the job identifier when you submit — without it you cannot investigate a stuck job at all.

A debugging routine that works

When something breaks, go in this order: validate the image locally, submit again and capture the raw response, inspect the job error if one appears, then simplify the options and retry. Each step tests exactly one half of the request, which is why keeping the image and the generation parameters separate in your code pays off precisely when things go wrong.

With that, you have the full loop: prepare a first frame, set audio, resolution, and duration, submit asynchronously, and poll to completion — the same request whether you run it in curl or Python.

Related articles

View all articles →

Start building with persistent AI artifacts

Get your API key and call image, video and audio models through one task-based API.

Read the API docs