Integrating an image generation API involves more than generating one image. Verify the endpoint, input type, output format, result lifetime, billing unit, and repeatable quality criteria.
Different image models may use OpenAI-style image APIs, vendor-specific APIs, or asynchronous tasks. Do not guess the request path based on the model name, confirm it from the current model page and API documentation first.
Four things to confirm before connecting
- The exact model ID available for the current account.
- Confirm whether the model supports text-to-image, image editing, or reference-image generation.
- Whether the request returns synchronously or creates an asynchronous task.
- Whether the result returns a URL, Base64, file object, or task ID.
View firstCurrent models and prices, and then copy the corresponding endpoints and fields from the API documentation.
Create a minimum request
The following is a general request skeleton, which does not mean that all image model fields are exactly the same:
export IMAGE_API_URL="from current API Full image-generation endpoint copied from the documentation"
export API_KEY="your temporary test Key"
curl "$IMAGE_API_URL" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "Accurate model in consoleID",
"prompt": "Blue ceramic cup on white background，Front product photography，Soft studio lighting"
}'Optional parameters such as size, aspect ratio, quality, reference image, transparent background or seed are only added if explicitly supported by the current document. If too many parameters are added at one time, it will be difficult to determine whether the field is not supported or there is a model problem after failure.
Handle generated results correctly
URL results
If the response returns a temporary URL:
- Instantly download to your own object storage.
- Log HTTP status,
Content-Typeand file size. - Do not treat temporary URLs as permanent material addresses.
- Set limited retries and total timeout for failed downloads.
Base64 results
First verify whether decoding is successful and whether the file header is correct before writing to storage. Do not put complete Base64 into ordinary business logs, otherwise the log volume and privacy risks will increase rapidly.
Asynchronous tasks
Save the task ID and query the status using a capped polling interval. distinguish queued、running、succeeded、failed and timeout, do not re-create the same task immediately after the client request times out.
Use fixed question sets to check quality
Prepare at least four types of prompt words, and generate each type multiple times:
| question type | Key inspections |
|---|---|
| Product picture | Complete subject, material, background, text and brand elements |
| Figures | Hands, facial features, clothing, multi-person relationships and consistency |
| Poster image | Composition, white space, text readability and sizing |
| Picture editing | Whether the unedited area maintains consistency with mask boundaries and reference images |
Record availability, number of reworks, generation time, file size and sheet cost for each set. Saving only the best picture will cover up model stability issues.
How to record costs and retries
Image tasks are usually charged based on the number of images, size, quality or model level, and the text token formula cannot be used directly. It is recommended to save:
{
"model": "MODEL_ID",
"task_type": "text_to_image",
"width": 0,
"height": 0,
"quality": "VALUE_FROM_REQUEST",
"attempts": 1,
"status": "succeeded"
}Account reconciliation shall be based on console records. Application-side data is used to locate high-rework question types, repeated generation, and abnormal failures.
Common mistakes
400 or parameter not supported
Return to the current model document, delete unnecessary parameters, and keep only the model and prompt words. Do not copy fields from another supplier directly.
404 or model not found
Requery the model catalog and copy the exact ID. Confirm that the model belongs to the image endpoint and not the multimodal chat model.
Return successfully but no picture
Check response type: may return task ID, temporary URL, Base64 or nested data structure. Save the masked response structure, don't just check the HTTP status.
Download link expires soon
Temporary results should be dumped immediately after successful generation. The business database saves its own object storage address and original task ID.
Image quality fluctuates
Fixed prompt words, reference images, dimensions and other supported parameters for comparison after multiple generations. Model stochasticity, content security policies, and routing changes can all affect results.
Check before going online
- The model ID and endpoint come from the current console and documentation.
- There are processing branches for synchronous, asynchronous and failure states.
- The temporary URL will be transferred immediately.
- Logs do not record full images, Base64 or API keys.
- The fixed question set has been retested many times.
- There are upper limits for single task timeouts, polling, and retries.
- The number of reworks and complete task costs were recorded.
After completing the minimum access, read againModel selection methodandAPI Cost Control, don’t decide to produce a model based solely on a single display effect.