Tutorial
How to Call fibo-2.0/text-to-image via the HiAPI API: curl and Python
On this page
What this tutorial builds
This is a hands-on walkthrough for getting a real image back from fibo-2.0/text-to-image on HiAPI. By the end you will have two things you can run immediately: a curl command that produces a valid image generation request, and a small Python function that does the same thing and returns the result for further processing.
We will move in the order most developers actually work. First, confirm the environment and credential are in place. Then read the request body field by field so you know what each part controls. Then send the call with curl to prove the endpoint, key, and payload all line up. Only after that do we port the same request into Python, where the interesting work — parsing the response, handling failures, and wrapping it in a function — begins.
The goal is not to enumerate every possible parameter. It is to give you one request shape you fully understand, so you can adapt the prompt, the output size, and the surrounding code to your own use case without guesswork.
Before you send the first request
Three things need to be true before your first call succeeds.
A HiAPI account and API key
Requests to fibo-2.0/text-to-image are authenticated. Generate an API key in your HiAPI account and keep it out of source control. The examples below read the key from an environment variable rather than hardcoding it — do the same from day one, because retrofitting secret handling later is tedious.
export HIAPI_API_KEY="your-api-key-here"
A tool that can send HTTP requests
For the curl walkthrough you need curl on your machine. It ships with macOS and most Linux distributions; on Windows it is available in current builds and in Windows Terminal. For the Python section you need Python 3 and the requests library, which is the most common way to make HTTP calls from a script. If you do not have it yet:
pip install requests
A clear idea of what you want to generate
Have a prompt ready. Image models respond strongly to specific, concrete descriptions — subject, style, lighting, and composition — so a one-line idea is usually enough to start testing. You will refine it after you see the first result; that is the normal loop.
Once those three are in place, everything else is about the request body.
The request, field by field
A fibo-2.0/text-to-image call is a POST with a JSON body. The body is small: a prompt and the settings that shape the output. Rather than memorizing a full payload, understand each field so you can change it deliberately.
The model identifier
The endpoint path itself names the model: fibo-2.0/text-to-image. You do not need to pass a separate model string in most cases — the route you call determines which model runs. If your integration supports routing through a shared endpoint, keep the model name in one configuration constant so you can switch it without touching call sites.
The prompt
This is the core input: a text description of the image you want. Treat it as a specification, not a wish. Naming the subject, the visual style, and the composition gives the model more to work with than an abstract concept. Keep prompts in a variable or a separate file so you can iterate quickly without rewriting the request code.
Output settings
Image requests typically carry a small set of output controls — most commonly the dimensions or aspect ratio of the generated image, and a count if you want more than one result. Use the field names documented for fibo-2.0/text-to-image in the HiAPI model reference; the example payloads below use those canonical names. If a setting is not documented for this model, leave it out rather than guessing — unknown fields are a common source of validation errors.
What not to put in the body
Do not put your API key in the JSON body. Authentication belongs in the request headers. Keeping credentials out of the payload means the body is safe to log and diff while debugging, which you will appreciate the first time a request fails.
A working curl request
Here is a complete call. Substitute your own prompt and run it from a shell where HIAPI_API_KEY is set.
curl -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "a quiet harbor at dawn, soft mist over the water, wide composition, photographic style",
"size": "1024x1024",
"n": 1
}'
What each part does
-X POSTsets the HTTP method. Image generation is a create operation, so it is a POST, not a GET.- The URL points at the
fibo-2.0/text-to-imageroute on the HiAPI API host. If your account uses a regional or project-specific base URL, substitute that host and keep the path. Authorization: Bearer $HIAPI_API_KEYpasses your key from the environment. The shell expands the variable, so the secret never appears in your command history as a literal string.Content-Type: application/jsontells the server the body is JSON. Without it, many gateways reject the request before it reaches the model.-d '...'is the JSON body: the prompt, the requested size, and a count of one image.
Verifying the result
Run the command and look at the raw output first. A successful call returns a JSON document describing the generated image; a failed call returns an error object. Before you build anything on top, confirm you can tell those two apart by eye. If the response is large, pipe it through a formatter such as jq so the structure is readable:
curl -s -X POST "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"a quiet harbor at dawn","size":"1024x1024","n":1}' | jq .
Once one manual call works, you have eliminated the credential and payload as suspects. Everything that goes wrong after this point is in your code.
The same call in Python
The Python version does exactly what the shell command did, but gives you a place to validate inputs, retry, and store results. Keep it small and explicit.
import os
import requests
API_URL = "https://api.hiapi.ai/v1/models/fibo-2.0/text-to-image"
def generate_image(prompt: str, size: str = "1024x1024", n: int = 1) -> dict:
api_key = os.environ["HIAPI_API_KEY"]
payload = {
"prompt": prompt,
"size": size,
"n": n,
}
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json",
},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = generate_image(
"a quiet harbor at dawn, soft mist over the water, wide composition, photographic style"
)
print(result)
Why it is written this way
- The key is read from the environment inside the function, so the call fails loudly at startup if it is missing rather than sending an unauthenticated request.
json=payloadletsrequestsserialize the body and set the content type correctly. Do not hand-build JSON strings in Python; it invites quoting bugs that are invisible until runtime.timeout=60makes slow failures explicit. Image generation is not instantaneous, so choose a timeout you are comfortable waiting for, but always set one.raise_for_status()turns 4xx and 5xx responses into exceptions. That single line is what stops a failed call from being silently treated as a success.- The function is parameterized on
prompt,size, andnso the rest of your program can call it like any other library function.
Run the file, and you should see the same JSON structure the curl call returned.
Reading the response and handling errors
A successful response gives you a JSON object describing the generated output. The details you care about are the generated image itself — typically a URL or reference you can download or store — and any metadata the API returns about the request. Parse the response as data; do not scrape it with string operations. If the shape is not what you expected when you first inspect a live response, check the model reference before adjusting your parser, since guessing at field names is how integrations quietly break.
Detecting failure
There are three layers of failure worth handling deliberately.
Transport errors. The request never completed: DNS failure, connection reset, timeout. In Python these surface as requests.exceptions, and they are safe to retry with backoff.
HTTP error status. The server answered but rejected the request. A 401 usually means the key is missing or wrong; a 4xx validation error usually means a field name or value is off; a 429 means you are sending too fast; a 5xx means something failed on the server side. raise_for_status() catches all of these as one exception, so inspect the response body for the message before deciding what to do.
A 200 with an unexpected body. This is why you validate structure rather than assuming. Check that the fields you depend on are present before using them, and treat a missing image reference as a failure even if the status code was 200.
try:
result = generate_image("a quiet harbor at dawn")
image = result.get("data", [{}])[0]
except requests.HTTPError as exc:
print("request failed:", exc.response.status_code, exc.response.text)
The habit that matters: never drop an error silently. Log the status code and the response body at minimum, because that pair tells you whether to fix your payload or wait and retry.
Taking it toward production
Once a single call works and failures are visible, a few small habits make the integration hold up under real traffic.
Retry only what is safe to retry
Transport errors, timeouts, 429s, and 5xx responses are worth retrying with exponential backoff and a cap on attempts. Validation errors and 401s are not — retrying a malformed request just burns quota. Distinguish the two classes explicitly in your error handling.
Keep configuration out of code
Put the API base URL, the model path, the default size, and the timeout in configuration, not scattered through functions. When you move from testing to a different environment, or later try a sibling model, you change one place.
Log requests and responses, minus secrets
Log the prompt, the parameters, the status code, and a truncated response. Never log the API key. This is what lets you answer "why did this image come back wrong" a week later without reproducing it.
Validate inputs before sending
Check that the prompt is non-empty and within reasonable length, and that size and n match the values the model documents. Catching a bad value locally is faster and cheaper than a round trip.
Store results, do not just print them
Generated image references can be transient. Download or copy the output to your own storage as part of the same job, and record which prompt and parameters produced it. That record is what makes regeneration and auditing possible.
Wrap fibo-2.0/text-to-image behind the small generate_image function from this tutorial and let the rest of your application depend on that function rather than on the raw HTTP call. When you are ready to vary prompts at scale, the HiAPI model reference is the place to confirm the supported parameters before you widen the interface.
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