Tutorial
How to Use seedream-4.5/text-to-image via the HiAPI API: curl and Python Examples
A minimal, working integration walkthrough for developers
On this page
What seedream-4.5/text-to-image Gives You
seedream-4.5/text-to-image is a text-to-image endpoint exposed through the HiAPI API. You send a text prompt and a few optional parameters, and the model returns a generated image. You can use it to create scene illustrations, product mockups, concept art, or any visual where you need to render readable text inside the image—signage, labels, short headlines. The endpoint is stateless: each request is an independent generation, so you control repetition and variation from your application code.
Because it runs behind the same unified interface as other HiAPI models, you authenticate once, use the same base URL and error conventions, and switch models without learning a new integration pattern. The model detail page for seedream-4.5/text-to-image lists the current parameter names and accepted values—treat that page as the source of truth for fields, not this article.
Request Anatomy: What You Send and Get Back
Every text-to-image call has the same shape: a POST to the model's HiAPI endpoint with a JSON body. The body contains the fields the model needs; the response contains the generated image and metadata about the request.
What you send
prompt(string, required): the description of the image. This is the main control surface; see the prompting section below.aspect_ratioor a size-related field (optional): controls the output canvas shape. Use the exact field name from the model detail page—don't assume it matches another model's parameter name.- Any model-specific options (for example, style or quality hints) that the model page documents. Omit fields you don't need; the API applies defaults.
What you get back
A successful response is a JSON object. The fields you will actually read in code are typically:
- The image payload: either a URL to the generated image or a base64-encoded image string, depending on the response mode. Your code should handle the one the endpoint returns; the model page specifies which.
- Request metadata such as an identifier or status, useful for logging and support.
Not every field is guaranteed across versions, so validate the response shape rather than assuming a fixed schema. If you build a parser that only looks for the fields you need and treats everything else as optional, your integration will survive minor response changes.
Your First Working curl Request
The smallest useful call sends a prompt and nothing else. Replace the placeholder key and prompt with your own, then run it.
curl -X POST "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "A quiet street cafe at dusk, warm window light, a chalkboard sign reading OPEN",
"aspect_ratio": "1:1"
}'
Line by line:
- The URL points at the model's HiAPI endpoint. Keep the model identifier exactly as documented.
- The
Authorizationheader carries your API key. Using an environment variable keeps the key out of your shell history and source files. Content-Type: application/jsontells the server to parse the body as JSON.- The JSON body contains the prompt and an optional aspect ratio. Start with one image and one prompt; iterate on wording before adding options.
If the call succeeds, the response contains the image data described in the previous section. Save the output to a file (or open the returned URL) and inspect it before building further. If you get an authentication error, confirm the key is present and the header spelling is correct; if you get a parameter error, re-check field names against the model page.
The Same Request in Python
The Python version uses the standard requests library—no SDK required.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/models/seedream-4.5/text-to-image"
payload = {
"prompt": "A quiet street cafe at dusk, warm window light, a chalkboard sign reading OPEN",
"aspect_ratio": "1:1",
}
response = requests.post(
URL,
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
result = response.json()
print(result)
Two details matter here. First, pass json=payload rather than a hand-built string—requests sets the content type and serializes correctly. Second, set an explicit timeout. Image generation can take longer than a typical API call, so a generous timeout with a clear failure mode is better than a hung request.
The printed result is the raw response. In real code, pull out the image field your endpoint returns (URL or base64), then either download the URL with a second request or decode the base64 to bytes and write it to disk. Keep that extraction in a small helper function so tests and production code share the same parsing logic.
Prompting for Realism and Readable Text
Prompt quality drives output quality more than any other parameter. Two goals come up most often: photorealistic scenes and legible text inside the image.
Realism
Describe the scene the way a photographer would frame it: subject, lighting, time of day, lens feel, and environment. Concrete nouns beat abstract adjectives. Instead of "a nice coffee shop," write "a narrow coffee shop interior, midday light through a large window, wooden counter, shallow depth of field." Add a short style cue such as "photograph" or "documentary photo" to steer away from illustration. Keep one main subject per prompt; competing subjects tend to produce muddled compositions.
Readable text
When the image must contain words, put the exact text in quotes and keep it short. A sign reading OPEN or a label reading FRESH BREAD is far more reliable than a paragraph. Say where the text appears—"a chalkboard sign above the counter reading OPEN"—so the model knows the text belongs to an object. If text comes out garbled, shorten it, simplify the surrounding scene, and regenerate. Small wording changes are normal; expect a few iterations.
Iterating
Change one variable at a time: first the prompt, then the aspect ratio, then any style options. Save your prompts and the settings that produced good results. That record becomes your regen baseline and keeps debugging from turning into guesswork.
Choosing Aspect Ratios and Output Settings
The aspect ratio determines composition before the model draws anything. Pick it to match the destination, not to match a default.
- Square (
1:1): social posts, avatars, product tiles. Simple and safe. - Landscape (for example
16:9): banners, hero images, presentation slides. Encourage wide scenes—horizons, storefronts, wide interiors. - Portrait (for example
9:16): mobile screens, stories, posters. Prompts with a clear vertical subject—a standing figure, a tall building—work best.
If your prompt describes a wide scene but you request a portrait canvas, the model has to crop or distort the composition. Match the description to the frame. For downstream pipelines, generate at a size that fits your largest use case and downscale later; upscaling a small image rarely looks right. When you need several formats, generate separate calls per ratio rather than cropping one image into every layout.
Output settings beyond the ratio (quality hints, style controls) are model-specific. Set only what the model page documents, and treat every extra parameter as a variable to test, not a default to copy.
Handling Errors and Rate Limits
Production integrations fail for predictable reasons: bad keys, invalid parameters, timeouts, and throttling. Handle each class explicitly.
Validate before parsing
Check the HTTP status code first. 2xx means success—then parse the body. 4xx usually means a problem with your request: unauthorized keys, malformed JSON, or an unsupported parameter value. These will not fix themselves on retry; log the response body, surface it to the caller, and fix the request. 5xx indicates a server-side problem and is often transient.
Retry with backoff
Retry only the failures that can succeed later: 429 responses, timeouts, connection errors, and most 5xx codes. Use exponential backoff with jitter—wait a short base interval, double it each attempt, and cap the total attempts. Never retry a 400 or 401; you will just burn quota.
import time, random
def generate(payload, max_attempts=5):
for attempt in range(max_attempts):
try:
r = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
except requests.RequestException:
pass # network error: retry below
else:
if r.status_code == 200:
return r.json()
if r.status_code not in (429, 500, 502, 503, 504):
raise RuntimeError(f"unrecoverable: {r.status_code} {r.text}")
time.sleep(min(2 ** attempt + random.random(), 30))
raise RuntimeError("exhausted retries")
Respect limits
Keep request volume under the rate limits shown for your account, and treat 429 as a signal to slow down rather than to retry harder. Add concurrency caps in workers, and log every attempt with the request ID so throttling and failures are diagnosable after the fact. Because image calls are billed by generated output, retries that produce images are not free—validate inputs before firing requests.
From Test Call to Production Checklist
Before you ship, confirm the operational basics:
- Key management: keys live in environment variables or a secrets manager, never in source control. Rotate them on a schedule and on any suspected exposure.
- Timeouts: every outbound call has an explicit timeout, and your caller has a plan for what to do when it fires.
- Logging: record request ID, prompt version, parameters, status, and latency for every call. Redact keys and full payloads where required.
- Prompt versioning: store prompts and the settings that produced accepted outputs, so you can reproduce and roll back.
- Cost awareness: generation is billed by output, so cap batch sizes, avoid unnecessary retries, and cache results you will reuse.
- Graceful degradation: when generation fails after retries, fall back to a cached image or a placeholder rather than breaking the page.
Start with the single curl call from this guide, move it into a small Python helper, and only then add concurrency and batching. The model reference for seedream-4.5/text-to-image is the place to confirm field names as you expand the integration.
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