Blog

Tutorial

How to Use topaz-upscale/video via the HiAPI API: curl and Python Recipes

Nov 17, 2026 13 min read
Cover image: several translucent glass sheets overlapping at restrained angles, refracting cool blue parallel color bands against a light background, with no text in the frame.
On this page

What topaz-upscale/video Does and When to Reach for It

topaz-upscale/video is a video enhancement endpoint on HiAPI. You send it a source video plus instructions, and it returns an enhanced video: higher resolution, reconstructed fine detail, and optionally smoother motion through frame interpolation. It is the endpoint you reach for when the footage already exists and the problem is quality, not content generation.

Where it fits

Typical jobs that map cleanly onto this endpoint:

  • Archival and legacy footage — old captures, compressed screen recordings, or inherited media that needs to look presentable at modern resolutions.
  • Rendering pipelines — finished sequences rendered at low resolution for speed, then enhanced for delivery.
  • Motion cleanup — low-frame-rate source that needs interpolated frames to avoid stutter on playback.
  • Delivery variants — one master, several output tiers, with enhancement applied per tier.

When to choose it over alternatives

The decision usually comes down to three questions:

  1. Is the problem resolution and detail, or is it content? If you need new pixels invented wholesale (a scene that was never shot), this is the wrong tool. Enhancement assumes a real source frame underneath.
  2. Can your pipeline tolerate asynchronous work? Video jobs are not instant. If your UX demands sub-second response, this endpoint belongs in a background job, not a request handler.
  3. Do you need frame interpolation as well as upscaling? If motion smoothness matters, you want both capabilities in one pass rather than chaining separate tools. topaz-upscale/video covers both.

If your source is a single still image, use an image upscaler instead. If your source is fine but your encoding is bad, fix the encode first — enhancement cannot recover detail that a heavy compression pass already destroyed, and you will pay for compute without gaining quality.

Preparing Your Request Before the First Call

Most first-call failures come from missing pieces rather than bad prompts. Get these in place before you write any code.

Account and credentials

You need a HiAPI API key with access to topaz-upscale/video. Keep the key in an environment variable rather than in source — every example below reads HIAPI_API_KEY from the environment.

export HIAPI_API_KEY="your-key-here"

Reachable source media

The model must be able to fetch your input. Two reliable patterns:

  • Public or signed URL — a URL the service can download without interactive auth. If your storage requires signed links, generate one with a generous expiry and remember to regenerate it on retries, or long jobs will fail partway through.
  • Upload first — push the file through the platform's upload mechanism and reference the returned identifier. This is the safer option for large files and for anything behind a private network.

Source characteristics worth checking

Before you spend a call, confirm:

  • Duration. Long videos mean long jobs. If you are testing, clip a 5–10 second segment from the middle of the source — the middle is usually more representative than the opening frames.
  • Codec and container. Exotic codecs sometimes fail to decode. Re-mux to a common container if in doubt.
  • Frame rate. Note it precisely; you will need it when reasoning about frame interpolation.
  • Resolution. Record the exact source dimensions so your before/after comparison is honest.

Know your output target

Decide the output resolution and frame rate before the first call, not after. Enhancement settings that make sense for a 720p source heading to 1080p are different from a 480p source heading to 4K. Write the target down; you will reuse it across every subsequent request.

Making the Call with curl

The request is a single POST to the topaz-upscale/video endpoint with a JSON body. Here is a complete, runnable example — substitute your own media URL.

curl -sS https://api.hiapi.ai/v1/video/enhance \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "topaz-upscale/video",
    "input": {
      "video": "https://your-bucket.example.com/clips/source_720p.mp4"
    },
    "parameters": {
      "target_resolution": "1080p",
      "target_fps": 60,
      "interpolation": "smooth",
      "detail": "balanced"
    },
    "prompt": "Restore fine texture on fabric and skin, keep grain natural, interpolate to 60fps without ghosting"
  }'

Reading the response

The immediate response acknowledges the job. You will get back a job identifier and a status field. Video work is asynchronous, so the practical pattern is:

# 1. Submit and capture the job id
JOB_ID=$(curl -sS https://api.hiapi.ai/v1/video/enhance \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | jq -r '.id')

# 2. Poll until the status is terminal
curl -sS "https://api.hiapi.ai/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .output'

Three fields matter when you read the result:

  • status — moves from queued to running to a terminal state. Treat anything unrecognised as "keep waiting", not as success.
  • output — present on success and contains the URL or identifier of the enhanced video.
  • error — present on failure. Read the message literally; it usually names the offending field.

If you are iterating on prompts, put the body in a file (request.json) and use -d @request.json. It keeps your shell history clean and lets you diff versions of the same request.

Calling the Same Endpoint from Python

The Python version is a thin wrapper over the same HTTP contract. Use requests, keep the key in the environment, and wrap the submit-and-poll cycle in a function so callers do not need to know it is asynchronous.

import os
import time
import requests

BASE = "https://api.hiapi.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

def enhance_video(
    video_url: str,
    prompt: str,
    target_resolution: str = "1080p",
    target_fps: int = 60,
    poll_interval: float = 5.0,
    timeout: float = 1800.0,
) -> str:
    payload = {
        "model": "topaz-upscale/video",
        "input": {"video": video_url},
        "parameters": {
            "target_resolution": target_resolution,
            "target_fps": target_fps,
            "interpolation": "smooth",
            "detail": "balanced",
        },
        "prompt": prompt,
    }

    resp = requests.post(f"{BASE}/video/enhance",
                         headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    job_id = resp.json()["id"]

    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        r = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        if data["status"] == "succeeded":
            return data["output"]["video"]
        if data["status"] == "failed":
            raise RuntimeError(data.get("error", "enhancement failed"))
        time.sleep(poll_interval)

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

Notes on using it in a real pipeline

  • Exponential backoff on polling. Fixed five-second intervals are fine for a shell script; for production, back off and cap the interval. Long videos can take a while, and polling harder does not make them finish sooner.
  • Idempotency. If your submit call times out, you may not know whether the job started. Log the request body alongside the job id so you can reconcile duplicates rather than blindly resubmitting.
  • Persist the job id. Write it to your database the moment you receive it. If the process dies mid-poll, you resume by id instead of paying for a second enhancement.

Prompt Recipes for Frame Interpolation

Frame interpolation is where prompts most often go wrong — either too vague to steer anything, or so prescriptive that the model chases contradictory goals. The prompt sits alongside structured parameters; keep the wording about intent and motion character, and let parameters carry the numeric targets.

Pattern: state the motion, not the maths

Weak:

interpolate

Better:

Interpolate to a smooth 60fps. Preserve the original motion cadence — no speed changes. Pans and camera moves should be linear and steady; avoid warping at frame edges.

You have already told the API the target frame rate in parameters. The prompt should describe what smooth motion looks like for this footage.

Pattern: name the artefacts you want avoided

Smooth 24p to 60fps. Avoid ghosting on fast-moving hands and avoid smearing around thin objects like railings and hair. Static backgrounds must stay perfectly still.

Naming specific failure modes is far more effective than "high quality". The model can check its own output against a concrete instruction.

Pattern: separate motion from texture

Focus on motion smoothness only for this pass. Leave the existing detail and grain untouched — texture restoration is handled separately.

Useful when you are chaining two passes, so each prompt has one job.

Pattern: handle mixed-motion footage

Interview clips with a locked-off camera but a moving subject respond well to camera stillness being called out explicitly:

Interpolate to 60fps. The camera is locked off — the background must not move or shimmer at all. Only the speaker's head and hands should show smooth motion.

Resist the urge to write an essay. Three sentences covering target motion, artefacts to avoid, and what must stay static covers almost every case.

Prompt Recipes for Detail Reconstruction

Detail reconstruction is the half of the job that invents plausible fine structure. The failure mode is hallucinated texture: skin that looks like plastic, foliage that turns into noise, lettering that becomes gibberish. Prompts should set a ceiling on invention.

Pattern: anchor to the source

Reconstruct detail consistent with the source frame. Do not invent texture that is not implied by the original pixels. Where detail is genuinely lost, prefer a soft, believable result over sharpened noise.

This single instruction prevents most over-sharpening pathologies.

Pattern: name the materials in frame

Recover fine detail in fabric weave, hair strands, and skin pores. Keep skin tone natural and pores irregular — avoid a smoothed, airbrushed look. Metal surfaces should keep their existing highlights and not gain new ones.

Material-specific instructions give the model constraints it can act on without needing a paragraph of generalities.

Pattern: protect text and graphics

This clip contains on-screen captions and a logo. Text must remain crisp and legible with no warping. Do not redraw or restyle any graphic elements.

Text is the highest-stakes detail — a garbled caption is worse than a slightly soft one. If legibility is critical, verify it in your comparison pass rather than trusting the prompt.

Pattern: dial sharpening deliberately

Apply a restrained amount of detail recovery. The target is natural-looking footage at 1080p, not a sharpened still frame. Slight softness is acceptable; ringing and halos are not.

Combining both

When you interpolate and reconstruct in one pass, write one prompt covering both, but keep each clause about exactly one concern:

Reconstruct fine texture — fabric, hair, skin — consistent with the source, avoiding plastic smoothing. Interpolate to 60fps with steady motion, no ghosting on hands, and a completely static background.

Comparing Before and After Output

An enhanced video that looks impressive on one frame can fall apart in motion. Build a fixed comparison routine and run it every time you change a parameter or prompt; otherwise you are guessing, and you will guess expensively.

Build a standard test clip set

Pick three short clips (5–10 seconds each) and never change them:

  1. Easy — well-lit, slow motion, clean source. Should look near-perfect; if it does not, something is misconfigured.
  2. Hard — fast motion, fine detail, or mixed motion types. This is where interpolation artefacts appear.
  3. Adversarial — on-screen text, thin structures, or heavy prior compression. This is where hallucination shows.

Run every prompt or parameter change against all three. A change that helps the easy clip and damages the adversarial one is not an improvement.

Compare in this order

  • Side by side at 100% zoom. Not at fit-to-window, where artefacts hide. Check the same crops: a face, a text region, and a high-motion area.
  • Frame-by-frame scrub. Step through a fast-motion section one frame at a time and look for ghosting, warping, and flicker.
  • Playback at real speed. Many artefacts vanish in scrub and appear in motion, or vice versa. Watch both.
  • Text legibility check. Read every caption in the enhanced version against the source. This is the fastest objective pass/fail available to you.

Judge cost alongside quality

Billing follows the work the endpoint does — output duration and resolution are what drive it; check the site's pricing panel for current rates. The practical consequence: a longer clip with a marginal quality gain is often a worse trade than a shorter clip with a clear one. For each candidate configuration, note the output duration and resolution you produced and ask whether the visible improvement justifies that spend. Keep the winner, discard the rest, and before you wire the endpoint into an automated pipeline, freeze one configuration and record it — prompt, parameters, and test results — so future changes can be measured against something.

Troubleshooting Common Request Problems

Most integration friction with topaz-upscale/video falls into a small number of buckets. Work through them in this order.

Authentication and access

A 401 means the key is missing, malformed, or not being sent — check that the environment variable is actually set in the shell running the command, not just in your editor. A 403 usually means the key is valid but the account lacks access to this model. Confirm the model name is spelled exactly topaz-upscale/video.

The service cannot fetch your video

This is the most common failure. Symptoms: the job fails early with a download or input error. Causes:

  • The URL is private or requires interactive login.
  • A signed URL expired before the job reached the download step — especially likely on long queues.
  • The host blocks automated requests or is slow enough to time out.

Fix: upload the file through the platform and reference the returned identifier, or generate a signed URL with a generous expiry at submit time.

Decode failures

If the error mentions the media rather than the request, re-mux the source to a common container and retry. Test the file locally first — if your own player struggles, the service will too.

Job runs forever or times out

Long sources take a long time, and some requests take disproportionally longer. Before resubmitting, check the job status by id — you may be looking at a queued job, not a failed one. Resubmitting blindly can double your spend. If polling from a script, make sure your own client timeout is longer than the expected job duration, otherwise you will abandon jobs that are still running fine.

Output looks worse than the source

The request succeeded but the result is over-sharpened, plastic, or ghosting. This is a prompt problem, not an API problem: go back to the detail-reconstruction and interpolation recipes and add explicit ceilings — "consistent with the source", "no ghosting", "background must stay static". Then re-run your standard comparison set.

Intermittent, non-reproducible failures

Log the full request body and the job id together on every call. Without both, you cannot tell whether a failure came from a different payload or a transient service issue. With a dozen logged failures, patterns usually emerge within minutes.

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