Blog

Tutorial

How to Call fibo-edit-1.5 Image-to-Image via the HiAPI API: curl and Python Guide

A working request walkthrough for instruction-based image editing

Nov 17, 2026 9 min read
Cover image: on a near-black background, a band of mint green dots that goes from sparse to dense, with a cluster of deep cyan dots accenting the right edge.
On this page

What the fibo-edit-1.5 image-to-image endpoint does

fibo-edit-1.5/image-to-image is an instruction-driven image editing endpoint. Instead of describing a scene from nothing, you hand the model a reference image plus a natural-language instruction, and it returns a new image that applies that edit while keeping the rest of the composition intact.

That framing matters for how you design requests. The reference image carries the visual context — subject, framing, lighting, style — and the instruction carries the change. A good instruction is specific about what changes and quiet about what should stay the same. "Replace the sky with a cloudy sunset, keep the buildings and foreground untouched" communicates more than "make it prettier."

A successful call produces an edited image asset. Depending on how the endpoint is invoked, the response returns the generated output in a form you can persist or fetch — see the endpoint reference for the exact response shape and supported parameters. Treat that reference as the source of truth for field names, accepted image formats, and size limits, since those details can evolve independently of this walkthrough.

Typical uses include product photo touch-ups, background swaps, style adjustments, and localized edits where regenerating the whole image would lose fidelity. If your task is generation from text alone rather than editing, this endpoint is the wrong tool; reach for a text-to-image model instead.

One expectation to set early: editing is iterative by nature. Your first instruction rarely lands perfectly, so build your workflow around cheap iteration — change one variable at a time, keep the reference image stable, and compare outputs before moving on.

Anatomy of a working request

Before writing any code, map out the inputs a request needs. Every call to fibo-edit-1.5/image-to-image combines four kinds of information.

Authentication

All requests go through the HiAPI unified interface with your API key in an Authorization header. Keep the key in an environment variable rather than in source, and never commit it.

The reference image

You supply the source image the edit applies to. The common patterns are a public URL the service can fetch, or a base64-encoded payload embedded in the JSON body. URLs are simpler for iteration; base64 avoids depending on external hosting. Check the endpoint reference for which forms are accepted and any size or resolution constraints.

The edit instruction

This is a plain-language string describing the change. Write it as an imperative sentence, name the region or element being changed, and state what should be preserved. Avoid stacking several unrelated edits into one instruction — split them into separate calls so you can tell which one caused a bad result.

Output controls

Optional knobs such as dimensions, output format, or the number of candidate images. Keep these at defaults for your first call, then adjust deliberately. Every parameter you set is one more variable to rule out when something looks wrong.

A minimal request body therefore has two substantive fields — the image and the instruction — wrapped in a JSON object with your output preferences if any. If you can answer "which image, what change, what format do I want back" you have everything needed to write the call.

Making the call with curl

Start with curl: it isolates the HTTP layer, so if something breaks you know it is the request and not your application code.

Export your key first:

 export HIAPI_API_KEY="your-api-key"

Then send a JSON body with a reference image URL and an instruction:

curl -sS https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/input.jpg",
    "prompt": "Replace the plain sky with a soft sunset gradient; keep the buildings and foreground unchanged."
  }'

A few practical notes:

  • Confirm the base URL and path against the endpoint reference rather than copying them from memory.
  • Use -sS so curl stays quiet on success but still surfaces transport errors.
  • If you prefer not to depend on external hosting, base64-encode the file and swap the image value for the encoded string, matching whatever field name the reference specifies.
  • Pipe the output through jq . while exploring to make the response readable.

To confirm the response, look for the returned image payload or URL and open it. If the body contains an error object instead, note its type and message fields — those tell you whether the problem is the image, the instruction, or the request shape. Save one good raw response to a file; it becomes your fixture when you write the Python client and your evidence when the behavior changes later.

The same request in Python

The Python version should mirror the curl call exactly — same path, same headers, same body — so any discrepancy is a bug in your code rather than a difference in what you asked for.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image"

payload = {
    "image": "https://example.com/input.jpg",
    "prompt": (
        "Replace the plain sky with a soft sunset gradient; "
        "keep the buildings and foreground unchanged."
    ),
}

response = requests.post(
    URL,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)
response.raise_for_status()
result = response.json()
print(result)

Sending a local file

If you are editing a file on disk, encode it and send the string instead of a URL:

import base64

with open("input.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload = {
    "image": encoded,
    "prompt": "Make the background a clean neutral gray; keep the product sharp.",
}

Verify the exact field name and expected encoding in the endpoint reference before relying on this.

Storing the output

Write the returned image to disk so you can compare iterations side by side and keep a record of which instruction produced which result. A small helper that saves the output under a name derived from a hash of the instruction makes later diffing trivial.

Always set an explicit timeout. Image editing takes longer than simple text calls, and an unbounded request will hang your worker indefinitely when the network stalls.

Handling errors and retrying safely

Failures fall into a few broad categories, and each deserves a different response.

Client-side errors

The request itself is wrong: malformed JSON, a missing image field, an unsupported image format, an instruction the model cannot act on, or authentication problems. Retrying these unchanged wastes time and quota — they will fail identically. Fix the request instead. When you see one of these, log the full request body (with the image truncated) and the error message, then correct the input.

Rate limiting

You are sending requests faster than your allowance permits. The right response is to back off and retry, not to hammer the endpoint. Respect any retry hint the response provides; otherwise use exponential backoff.

Server-side and transient errors

Timeouts, connection resets, and upstream hiccups are worth retrying. These are exactly what idempotent retry logic is for.

A practical retry policy

  • Retry only on timeouts, connection errors, and rate-limit or server-side responses.
  • Use exponential backoff with a cap — for example, start with a short delay, double it each attempt, and stop after a small fixed number of tries.
  • Add jitter to the delay so parallel workers do not all retry in the same instant.
  • Never retry a request that was rejected for a schema, format, or instruction problem.
  • Log every attempt with its attempt number and outcome so you can see whether failures cluster.
import random, time, requests

def edit_with_retry(payload, attempts=4):
    delay = 1.0
    for i in range(attempts):
        try:
            r = requests.post(URL, headers=HEADERS, json=payload, timeout=120)
        except (requests.Timeout, requests.ConnectionError):
            pass
        else:
            if r.status_code < 400:
                return r.json()
            if r.status_code not in (429, 500, 502, 503, 504):
                r.raise_for_status()
        time.sleep(delay + random.uniform(0, 0.5))
        delay = min(delay * 2, 30)
    raise RuntimeError("edit failed after retries")

Treat this as a skeleton: align the retryable status codes with what the endpoint actually returns, and keep the policy in one place so every caller shares it.

Before you ship it

Run through a short checklist before wiring the endpoint into production.

Validate the happy path twice

Re-run your saved curl call and your Python client against the same input and confirm they produce equivalent results. If they diverge, your payloads are not actually identical.

Calibrate instructions on real inputs

Test your instructions against representative images, not just one sample. Editing quality depends heavily on how specific the instruction is and how well the reference image supports the change. Keep a small set of prompt-and-output pairs as a regression suite; when you tweak wording, you can see what improved and what broke.

Check limits and formats

Confirm accepted image formats, maximum dimensions, and any request size ceiling in the endpoint reference. Validate locally before sending — rejecting a bad image client-side is faster and cheaper than a round trip.

Verify secrets and logging

Ensure the API key comes from the environment, that request logs truncate image payloads, and that no key ends up in error reports.

Confirm failure behavior

Force a timeout and a malformed body in a staging environment and check that your retry policy does the right thing and that a permanent failure surfaces to a caller instead of disappearing.

Once these pass, the integration is boring in the best way. Start from the fibo-edit-1.5 image-to-image endpoint reference for the authoritative parameter list, then build outward from the working curl call.

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