Tutorial
How to Call minimax-h3-image Image-to-Image with curl and Python on hiapi
On this page
What the image-to-image endpoint expects
Before you write any code, it helps to know the shape of an image-to-image call. The minimax-h3-image image-to-image endpoint takes your reference image (or images) plus a text prompt and returns a fresh generation that follows the prompt while staying anchored to the references.
At a conceptual level, every request has three parts:
- Model routing — you address
minimax-h3-imagewith theimage-to-imagetask, all through the single hiapi endpoint. You do not need separate credentials or hosts per capability. - Inputs — a prompt string, one or more reference images (URLs or base64 payloads), and generation controls such as the resolution tier.
- Output contract — the call is asynchronous. You get back a task identifier, then poll for status and fetch the resulting image URL when the task completes.
That last point matters. Image-to-image is not a blocking call that hands you pixels in the same response. Treat the submit call as "enqueue a job" and plan your client around a task lifecycle from the start. If you design for synchronous behavior first, you will end up rewriting your integration later.
Because everything flows through one hiapi interface, the headers, authentication, and response envelope stay consistent across models and tasks. Learn it once for minimax-h3-image and the same patterns apply elsewhere on the platform.
A minimal working request
Start with the smallest request that proves your credentials, endpoint, and payload shape are correct. Resist the urge to add every optional field up front.
A minimal body contains:
- the model name
minimax-h3-image - the task type
image-to-image - a
promptdescribing the transformation you want - a single reference image field
- a resolution tier
Conceptually the payload looks like this:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "turn this sketch into a clean product render on a white background",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
Send it, confirm you receive a task id back, then poll once or twice manually to see the status transitions. If you get a task id, your connectivity and auth are fine and you can move on to building the real client. If not, stop and read the error body — it usually names the offending field directly.
Keep this request saved as a smoke test. When a later change breaks your pipeline, rerunning the minimal request tells you instantly whether the problem is your payload or your surrounding code.
Calling it with curl
curl is the fastest way to see the raw request and response. Build the JSON body in a file so you can edit it without fighting shell quoting.
cat > payload.json <<'JSON'
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "restyle this photo as a watercolor illustration",
"image": "https://example.com/reference.png",
"resolution": "1024"
}
}
JSON
curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
--data @payload.json
Two headers carry the weight: Authorization with your bearer token and Content-Type: application/json. Keep both out of version control — read the key from an environment variable rather than pasting it into the command.
When the submit succeeds, capture the returned task id and poll it:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
The response carries a status field and, once complete, the result. Use jq to pull out just the fields you care about:
curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .result'
This is also the easiest way to debug a payload: curl shows you exactly what you sent and exactly what came back, with nothing hidden by a client library.
Calling it with Python
The Python version should mirror the curl flow: submit, capture the id, poll until terminal, fetch results. Use requests and a Session so connection reuse and default headers are handled once.
import os
import time
import requests
BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
"Authorization": f"Bearer {KEY}",
"Content-Type": "application/json",
}
def submit(prompt: str, image: str, resolution: str = "1024") -> str:
body = {
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": prompt,
"image": image,
"resolution": resolution,
},
}
resp = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
resp.raise_for_status()
return resp.json()["id"]
def poll(task_id: str, timeout: float = 300, interval: float = 2.0) -> dict:
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
resp = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
data = resp.json()
status = data.get("status")
if status in ("succeeded", "failed"):
return data
time.sleep(interval)
raise TimeoutError(f"task {task_id} did not finish in {timeout}s")
if __name__ == "__main__":
task_id = submit(
"turn this image into a flat vector poster",
"https://example.com/reference.png",
)
print("submitted:", task_id)
result = poll(task_id)
print(result)
The key details: raise_for_status() turns HTTP errors into exceptions instead of silent failures, the polling loop has both a deadline and an interval, and the terminal states are explicit. Parse the result object for the image URL only after the status reaches a terminal value, never before.
Working with multiple reference images
A single reference image often is not enough. You may want to preserve a subject's face from one photo while borrowing composition from another, or blend a texture and a silhouette. Minimax-h3-image image-to-image supports multi-reference inputs through a plural image field.
Structurally, the input object can carry an image field for a single reference and an images array when you have several:
{
"model": "minimax-h3-image",
"task": "image-to-image",
"input": {
"prompt": "keep the person from the first image, use the background style of the second",
"images": [
"https://example.com/person.png",
"https://example.com/background.png"
],
"resolution": "1024"
}
}
Order carries meaning. Reference index 0 is your primary subject and later entries are supporting context, so phrase the prompt to match the order you send. If you get a result that ignores one reference, the usual cause is an ambiguous prompt rather than a broken field — make the prompt say explicitly which image drives which attribute.
Practical rules for multi-reference work:
- Keep the count tight. Use only the references a given prompt actually needs; adding extras dilutes control.
- Match aspect ratios where possible so the model is not forced to reconcile conflicting framing.
- Prefer public URLs or base64 consistently within one request rather than mixing transports.
Send a two-image request once during integration and verify both references visibly influence the output before you build richer logic on top.
Choosing a resolution tier
The resolution field selects an output tier for minimax-h3-image image-to-image. It is not just a cosmetic knob — it changes compute, response latency, and the size of the payload you end up handling.
How to reason about it:
- Pick the smallest tier that satisfies the destination. A thumbnail for a list view does not need the same tier as a hero banner. Downscaling a large output later wastes time and money.
- Expect latency to scale with resolution. Higher tiers do more work per request, so your polling timeout and interval budgets should reflect the tier you chose.
- Watch payload sizes. Base64 reference inputs and high-resolution outputs both inflate transfer size; if you are moving many images, keep an eye on request and response bodies.
Billing follows the resolution tier you request — a request is priced by the tier it runs at, so an oversized tier on a small use case quietly costs more than it should. Check the live rates on the pricing panel rather than hard-coding assumptions.
A sensible integration strategy is to develop against a mid tier for speed, then promote critical assets to a higher tier only after the prompt and reference set are settled. Changing resolution late invalidates your latency measurements, so benchmark at the tier you actually intend to ship.
Handling the async lifecycle
Every image-to-image call on hiapi follows the same loop: submit, capture the task id, poll until a terminal status, then fetch results. Making that loop robust is most of the work in a production client.
Submit and record
Treat the task id as your durable handle. Log it the moment the submit response arrives, before doing anything else — if the process crashes mid-poll, the id lets you resume instead of regenerating.
Poll with backoff
Fixed two-second polling is fine for interactive use but wasteful for long batches. Start with a short interval and increase it gradually, capping the maximum interval so you still detect completion promptly.
def next_interval(current: float, cap: float = 15.0, factor: float = 1.5) -> float:
return min(current * factor, cap)
Respect terminal states
Exit the loop on success or failure only. Treating any non-empty response as "done" is the most common async bug — you will end up reading results that do not exist yet.
Bound everything
Set a timeout per HTTP call, and set an overall deadline for the task. If the deadline passes, surface a clear error rather than spinning forever. For transient network errors, retry the poll with backoff; do not blindly resubmit, which can create duplicate work.
Clean up
Once results are fetched, persist the image URL or bytes to your own storage promptly. Task results are transient handles, not a long-term CDN for your application.
Troubleshooting and production checklist
These are the failures developers hit first with minimax-h3-image image-to-image, and the checks that prevent them.
First-run failures
- 401 / 403 — the bearer token is missing, expired, or has surrounding whitespace. Verify the environment variable is exported in the shell that runs the request.
- 422 or validation errors — inspect the error body; it usually points at the field. A common culprit is putting
promptat the top level instead of insideinput. - Malformed JSON — validate your payload file with
jq .before sending it.
Runtime failures
- Task never completes — confirm you are polling the endpoint with the id you actually received, not a placeholder. Check your deadline is long enough for the resolution tier.
- Empty result on a "done" task — read the status field precisely; failure states also return a body.
- Reference ignored — revisit prompt wording and reference ordering before blaming the model.
Pre-ship checklist
- API key and base URL read from environment variables, never committed.
- Every HTTP call has an explicit timeout.
- Polling uses bounded backoff with a hard overall deadline.
- Terminal statuses are handled explicitly; no fall-through to result parsing.
- Results are downloaded and stored by your app, not hot-linked from the task response.
- Multi-reference prompts name which image controls which attribute.
- Resolution tier is benchmarked at the value you intend to ship.
- Logs capture task ids so failed jobs can be traced and resumed.
Run the minimal request from earlier whenever something breaks — it isolates whether the issue is your payload or your surrounding code. With the request shape, curl and Python clients, multi-reference handling, and a disciplined polling loop in place, you have everything needed to ship minimax-h3-image image-to-image reliably on hiapi.
Related articles
View all articles →-
Tutorial
gpt-6.2-sol in Practice: 5 High-Value Uses of a Text Model in Business
-
Tutorial
gpt-6.2-astra Practical Guide: Integration and Implementation Key Points for 5 High-Value Text Scenarios
A Developer's Checklist from Scenario Selection to Engineering Implementation
-
Tutorial
Tripo H3.1 Practical Application Scenarios: 5 High-Value Use Cases and Implementation Essentials
From text-to-3D to multiview reconstruction: choosing the right mode and parameters by business scenario