Image Invocation Notes (Best Practices)

Image generation is a synchronous long-running request (usually 10–60 seconds), and its calling pattern differs from chat APIs. Please read this page thoroughly before scaling up.

Timeout and Retries

• Set the client timeout to ≥120 seconds; the default 30 seconds in HTTP libraries may cut off the connection before generation completes;
• An interrupted request may already be in the upstream billing flow—if it fails, the pre-authorized quota will be returned automatically, but do not retry in rapid succession immediately; exponential backoff is recommended (5s → 15s → 45s);
• 429 indicates rate limiting; see Rate Limits and 429 for handling.

Model and Aspect Ratio Selection

• Specify aspect ratio/resolution through the model name suffix (-portrait, -landscape, -2k, -4k, etc.), do not rely on the size parameter; see Image and Video Generation Models for the full rules;
• For batch scenarios, prioritize the -fast tier, and switch to the standard tier for refinement after validating the prompt;
• 4K models are more expensive and slower to generate; use them only in the final production stage.

Result Handling

• The returned image URL is time-limited; transfer it immediately to your own object storage after obtaining it, and do not hotlink;
• When returning base64, note that the response body is larger; the body limits of reverse proxies and gateways need to be increased;
• Billing is per request: one successful generation incurs one charge, and failures (upstream errors/timeouts) are not billed.

Cost Control

• First use small batches to calibrate the prompt template, then scale up after it stabilizes;
• Create a separate API token for image workloads and set a quota cap to prevent program bugs from exhausting the budget;
• Each charge can be checked against the console’s “Logs”, or reconciled using the Log Query API.