Skip to main content
Use the standard Gemini-native method when the client and every proxy in the request path can wait for the final image:
The model ID is part of the path. The body contains contents and optional generationConfig; there is no extra YingTu request envelope.

​
When synchronous fits

Synchronous generation works well for server-side tools and interactions whose timeout comfortably exceeds generation time. It is simpler than creating and polling a task because the HTTP response already contains the final Gemini payload. The choice is not only about code. A Pro 4K response can be much larger and slower than a Lite 1K response, and Base64 increases the JSON transfer size. Choose the model and size before setting client and proxy limits.

​
Read the complete response

Iterate over every candidate and part. Some successful responses contain text before the image, while others contain only an image. Use inlineData.mimeType to select the file extension and handle promptFeedback.blockReason when no candidate image is returned.
A client timeout closes the connection but does not prove that no provider work occurred. Use the asynchronous task method when the client cannot safely wait.

Open the synchronous API

Inspect the generic request, response, and error schemas.

Choose a model first

Match lifecycle, resolution, and relative cost to the job.

Use a background task

Return HTTP 202 and retrieve the result after the connection ends.
Last modified on September 2, 2026