Blog

Tutorial

muse-video-1.0 Image-to-Video API Tutorial: curl and Python Requests

Nov 13, 2026 11 min read
Cover art for the muse-video-1.0 tutorial: flat faceted mineral cross-section in teal on a deep petrol field.
On this page

What the muse-video-1.0 Image-to-Video Endpoint Expects

The muse-video-1.0/image-to-video endpoint turns a single still image into a short video. Before you write a single line of code, it helps to understand the shape of the request so you can assemble the payload correctly the first time.

At a high level, a call has four concerns:

  • Model routing — you address the model as muse-video-1.0/image-to-video through the HiAPI unified API.
  • Input image — the still frame that seeds the animation. This is the required creative input.
  • Generation options — audio behavior and duration tier, which shape the output rather than the source.
  • Asynchronous execution — generation does not return a finished video inline. You submit a job, then poll for its result.

That last point is the one developers most often miss. Because rendering takes time, the endpoint is job-based: the initial call acknowledges your request and gives you a handle, and you follow up with status checks until the video is ready. Plan your client around that two-phase flow from the start rather than bolting polling on later.

The request body itself is JSON. Fields are grouped so that the image lives in its own input block, while audio and duration sit alongside it as generation settings. Keeping this mental model — input versus options versus job lifecycle — makes the rest of this tutorial straightforward.

Authentication

Every request is authenticated with your HiAPI API key, sent as a bearer credential in the Authorization header. Treat the key as a secret: load it from an environment variable rather than hard-coding it in scripts you might share.

export HIAPI_API_KEY="your_api_key_here"

With the key exported, you have everything you need to reason about the request. The next sections build the payload piece by piece.

Preparing and Uploading Your First-Frame Image

The first-frame image is the creative anchor of the whole job. Whatever you supply becomes frame zero, and the model animates forward from there. Getting it right saves you wasted generations.

Practical guidance for the source frame

  • Use a clear, high-quality still. Content that reads well as a single frame gives the model the strongest starting point.
  • Pick an aspect ratio that matches your target output. A wide landscape image and a tall portrait image will lead to very different framing, so decide the orientation before you upload.
  • Avoid heavy motion blur or ambiguous subjects. A still that is already visually stable produces a more predictable animation.
  • Keep the file accessible to the request. Whether you pass a URL or an encoded payload, make sure the reference is reachable at the moment the job is submitted.

How the image enters the request

The image is supplied inside the input block of the JSON body. A minimal image input looks like this:

{
  "input": {
    "image": "https://your-host.example/first-frame.jpg"
  }
}

If your source image lives locally, host it somewhere the request can reach, or pass it in the encoded form the endpoint accepts. The key rule is that the value you put in input.image must resolve to real image content when the job is created — a broken or expired link will fail at submission time, not at polling time, which is actually a useful early signal.

Verify before you generate

A quick sanity check pays off: open the image URL in a browser, confirm it loads, then confirm the dimensions suit your intended output. A two-second check here prevents a confusing debugging session later.

Once your first frame is ready and reachable, you can move on to the generation options.

Setting Audio Parameters and Duration Tiers

Beyond the image, muse-video-1.0/image-to-video exposes two families of options that change the character of the output: audio behavior and duration.

Audio parameters

Audio is expressed as a field inside the request body alongside your input. Decide the intent before you call:

  • Silent output — leave audio disabled when you plan to add your own soundtrack in post or need a clean video track.
  • Audio enabled — turn audio on when the clip should carry its own sound. Check the option in the payload rather than assuming a default.

Because audio handling is a property of the request, not a post-processing step, it is worth locking down before you scale up. If your pipeline mixes silent and audio-enabled clips, model the choice as an explicit parameter in your own client code so it is never accidental.

Duration tiers

The endpoint lets you choose a duration tier for the clip. Treat duration as a deliberate creative and cost decision:

  • Shorter tiers suit quick previews, social snippets, and storyboard tests where you want fast feedback across many source images.
  • Longer tiers give the animation more room to develop and are better for hero shots or sequences that need to breathe.

Duration is billed by output seconds, so the tier you pick directly affects consumption. There is no benefit to rendering a long clip for a quick visual check — start short while you are iterating on your first frame, then promote the winning setup to a longer tier.

Assembling the options together

In JSON, the audio and duration settings sit next to the input block:

{
  "input": {
    "image": "https://your-host.example/first-frame.jpg"
  },
  "audio": true,
  "duration": "<duration_tier>"
}

Use the exact tier identifiers the endpoint documents rather than guessing values. The next section turns this into a runnable request.

A Working curl Request

With the payload assembled, here is the initial submission as a curl command. This creates the job; it does not return the finished video.

curl -X POST "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "image": "https://your-host.example/first-frame.jpg"
    },
    "audio": true,
    "duration": "<duration_tier>"
  }'

A few notes on the command:

  • The URL targets the model by name. You do not need a separate client per model; the path identifies muse-video-1.0/image-to-video.
  • The header carries your key. $HIAPI_API_KEY is expanded from the environment variable you exported earlier, so the secret never appears in the script itself.
  • The body is the payload you just built. The image URL, the audio flag, and the duration tier all travel together.

The response is a job acknowledgement: it includes an identifier for the job you just created. Copy that identifier — you will need it in the polling step. If you are just exploring, pipe the response through a JSON formatter so the job ID is easy to spot.

If the submission fails, the error is usually immediate and specific: a malformed JSON body, a missing image reference, or an unrecognized option value. That fast feedback loop is why it is worth testing the submission separately before wiring up polling.

The Same Request in Python

Most integrations end up in Python, so here is the equivalent submission using the standard library — no third-party SDK required.

import json
import os
import urllib.request

API_KEY = os.environ["HIAPI_API_KEY"]
ENDPOINT = "https://api.hiapi.ai/v1/muse-video-1.0/image-to-video"

payload = {
    "input": {
        "image": "https://your-host.example/first-frame.jpg"
    },
    "audio": True,
    "duration": "<duration_tier>",
}

request = urllib.request.Request(
    ENDPOINT,
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    method="POST",
)

with urllib.request.urlopen(request) as response:
    result = json.loads(response.read().decode("utf-8"))

job_id = result["id"]
print("Submitted job:", job_id)

This script mirrors the curl call field for field. A few habits worth adopting:

  • Keep the payload in a dict. Building it as a Python dictionary means you can feed the same structure to any HTTP library — urllib, requests, or an async client — without rewriting the logic.
  • Read the key from the environment. os.environ keeps credentials out of source control.
  • Parse the response as JSON immediately. Extract the job ID into a named variable so the polling step reads cleanly.

If you prefer the requests library, the only change is swapping the transport: construct the same payload dict and post it with your header set, then call .json() on the response. The endpoint, headers, and body stay identical.

With the job submitted and its identifier captured, the remaining work is waiting for the result the right way.

Polling the Async Job and Retrieving the Video

Video generation is not instant, so the endpoint is asynchronous. After submission you poll a job status to learn when the render is done, then retrieve the output.

The polling loop

A robust loop does three things: it waits between checks, it has a ceiling so it cannot run forever, and it distinguishes "still working" from "finished" and "failed."

import time
import urllib.request

STATUS_ENDPOINT = "https://api.hiapi.ai/v1/jobs/{job_id}"

def wait_for_video(job_id, max_attempts=60, interval=5):
    for attempt in range(max_attempts):
        url = STATUS_ENDPOINT.format(job_id=job_id)
        request = urllib.request.Request(
            url,
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        with urllib.request.urlopen(request) as response:
            status = json.loads(response.read().decode("utf-8"))

        state = status.get("status")
        if state == "succeeded":
            return status.get("output")
        if state == "failed":
            raise RuntimeError(f"Job {job_id} failed: {status}")

        time.sleep(interval)

    raise TimeoutError(f"Job {job_id} did not finish in time")

Design notes for production

  • Use a sensible interval. Five seconds is a reasonable starting point; do not hammer the status endpoint.
  • Always cap attempts. The max_attempts ceiling turns an infinite wait into a clear error you can log and alert on.
  • Handle the failure state explicitly. A failed job carries diagnostics — surface them rather than silently retrying the same input.
  • Persist the job ID. If your process restarts, you can resume polling instead of paying to regenerate.

Retrieving the output

When the job succeeds, the status response includes the output reference for the finished video. Download it to your own storage promptly rather than depending on a long-lived link. Once you hold the file locally or in your bucket, the generation is complete from your pipeline's perspective.

That is the whole lifecycle: submit, poll, retrieve. Keep the two phases separate in your code and each one stays simple.

Common Pitfalls and Debugging Tips

Most integration problems with muse-video-1.0/image-to-video fall into a small number of buckets. Here is what to check when something goes wrong.

Image input problems

  • Unreachable image reference. If the URL requires authentication or has expired, the job fails at submission. Host the frame somewhere publicly readable for the duration of the request.
  • Mismatched aspect ratio. A portrait still forced into a landscape output leads to awkward cropping or letterboxing. Set your source orientation to match your target.
  • Wrong content. It is easy to point at a thumbnail or placeholder instead of the real frame. Verify the URL opens the intended image.

Parameter mistakes

  • Guessing duration values. Use the exact tier identifiers the endpoint documents. An unrecognized value is a common source of rejection.
  • Forgetting the audio flag. If you omit audio settings and expect sound, you may get a silent clip. Be explicit about whether you want audio.
  • Mixing up top-level and input fields. The image belongs inside input; audio and duration are siblings of input, not children of it. Nesting errors produce confusing validation messages.

Polling errors

  • Treating submission as completion. The first response is an acknowledgement, not the video. Always follow up with a status check.
  • Polling without a limit. An uncapped loop will hang your worker if a job stalls. Add a ceiling and a timeout error.
  • Ignoring failures. A job that ends in a failure state will never produce a video; catch it and inspect the diagnostics instead of waiting.
  • Long waits on bad inputs. When a render is consistently failing, stop regenerating. Fix the source frame or parameters first, then resubmit.

A debugging sequence that works

  1. Confirm the image URL loads in a browser.
  2. Submit a minimal payload with only the image to isolate parameter issues.
  3. Validate the job ID came back cleanly.
  4. Poll manually at first, watching the status transition.
  5. Only then automate the loop and add retries around transient network errors.

Working through these in order quickly narrows a problem to one layer — image, options, or lifecycle — and keeps your integration moving. With the request shape, options, and polling flow understood, you are ready to build against the endpoint.

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