Rodin API: Hyper3D AI’s Proven Guide to Avoid Costly Errors

Submit, Poll, Download

Generation is asynchronous, so a Rodin API integration is a small state machine rather than a single request. You post a multipart form to /rodin, poll /status until every job finishes, then call /download and fetch the files. The sample below follows that flow, with explicit values for the settings most likely to surprise you.

import os, time, requests
API = "https://api.hyper3d.com/api/v2"
AUTH = {"Authorization": f"Bearer {os.environ['RODIN_API_KEY']}"}
with open("input.png", "rb") as img:
    r = requests.post(f"{API}/rodin", headers=AUTH, timeout=60,
        files=[("images", img)],
        data={"tier": "Gen-2.5-Medium", "mesh_mode": "Quad", "quality": "medium"})
r.raise_for_status()
task = r.json()
if task.get("error") or not task.get("uuid"):
    raise RuntimeError(task)
wait, deadline = 5, time.time() + 1200
while True:
    if time.time() > deadline:
        raise TimeoutError(task["uuid"])
    time.sleep(wait)
    s = requests.post(f"{API}/status", headers=AUTH, timeout=60,
        json={"subscription_key": task["jobs"]["subscription_key"]})
    if s.status_code == 429:
        wait = int(s.headers.get("Retry-After", 5))
        continue
    s.raise_for_status()
    states = [j["status"] for j in s.json()["jobs"]]
    if "Failed" in states:
        raise RuntimeError(states)
    if all(x == "Done" for x in states):
        break
    wait = min(wait + 5, 30)
d = requests.post(f"{API}/download", headers=AUTH, timeout=60,
    json={"task_uuid": task["uuid"]})
d.raise_for_status()
for f in d.json()["list"]:
    print(f["name"], f["url"])

Two Identifiers, Two Jobs

A task response carries several IDs, and mixing them up is the common mistake the errors page calls out. Status wants jobs.subscription_key. Download wants the top-level uuid, passed as task_uuid. Swap them and you get NO_SUCH_TASK, which looks like a lost job when it is really a wrong field.

Every entry in jobs.uuids is a third kind of ID, and it belongs in neither call. Name these fields clearly in your own database so nobody has to rediscover the difference during an incident. The same rules apply on Rigging and Rodin Agentic, although the agentic response names its object job rather than jobs.

A Sensible Polling Budget

Hyper3D’s guidance is specific: wait 5 seconds before the first check, back off progressively, cap the interval at 30 seconds, honour Retry-After, stop when any job fails, and set a client-side deadline. Its Python sample adds 5 seconds per poll and gives up after 20 minutes.

That schedule makes a worst case easy to budget. The first six intervals (5, 10, 15, 20, 25, 30) use 105 seconds, leaving 1,095 seconds at 30 seconds each, or about 37 more checks. Each Rodin API task therefore costs at most about 43 status calls, and far fewer for a job that finishes quickly.

The state list is short: Waiting, Generating, Done and Failed. While a job is Waiting, the response may include queue_length, an approximate count of the jobs ahead of it. Log that value, because it is the only hint you get about why a job is slow.