Gemini Image Generation API
curl --request POST \
--url https://www.token-nova.com/v1beta/models/{model}:generateContent \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"contents": [
{}
],
"contents[].role": "<string>",
"contents[].parts": [
{}
],
"contents[].parts[].text": "<string>",
"contents[].parts[].inlineData": {},
"contents[].parts[].inlineData.mimeType": "<string>",
"contents[].parts[].inlineData.data": "<string>",
"generationConfig": {},
"generationConfig.responseModalities": [
"<string>"
],
"generationConfig.imageConfig": {},
"generationConfig.imageConfig.aspectRatio": "<string>",
"generationConfig.imageConfig.imageSize": "<string>",
"safetySettings": [
{}
]
}
'import requests
url = "https://www.token-nova.com/v1beta/models/{model}:generateContent"
payload = {
"contents": [{}],
"contents[].role": "<string>",
"contents[].parts": [{}],
"contents[].parts[].text": "<string>",
"contents[].parts[].inlineData": {},
"contents[].parts[].inlineData.mimeType": "<string>",
"contents[].parts[].inlineData.data": "<string>",
"generationConfig": {},
"generationConfig.responseModalities": ["<string>"],
"generationConfig.imageConfig": {},
"generationConfig.imageConfig.aspectRatio": "<string>",
"generationConfig.imageConfig.imageSize": "<string>",
"safetySettings": [{}]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
contents: [{}],
'contents[].role': '<string>',
'contents[].parts': [{}],
'contents[].parts[].text': '<string>',
'contents[].parts[].inlineData': {},
'contents[].parts[].inlineData.mimeType': '<string>',
'contents[].parts[].inlineData.data': '<string>',
generationConfig: {},
'generationConfig.responseModalities': ['<string>'],
'generationConfig.imageConfig': {},
'generationConfig.imageConfig.aspectRatio': '<string>',
'generationConfig.imageConfig.imageSize': '<string>',
safetySettings: [{}]
})
};
fetch('https://www.token-nova.com/v1beta/models/{model}:generateContent', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://www.token-nova.com/v1beta/models/{model}:generateContent",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'contents' => [
[
]
],
'contents[].role' => '<string>',
'contents[].parts' => [
[
]
],
'contents[].parts[].text' => '<string>',
'contents[].parts[].inlineData' => [
],
'contents[].parts[].inlineData.mimeType' => '<string>',
'contents[].parts[].inlineData.data' => '<string>',
'generationConfig' => [
],
'generationConfig.responseModalities' => [
'<string>'
],
'generationConfig.imageConfig' => [
],
'generationConfig.imageConfig.aspectRatio' => '<string>',
'generationConfig.imageConfig.imageSize' => '<string>',
'safetySettings' => [
[
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://www.token-nova.com/v1beta/models/{model}:generateContent"
payload := strings.NewReader("{\n \"contents\": [\n {}\n ],\n \"contents[].role\": \"<string>\",\n \"contents[].parts\": [\n {}\n ],\n \"contents[].parts[].text\": \"<string>\",\n \"contents[].parts[].inlineData\": {},\n \"contents[].parts[].inlineData.mimeType\": \"<string>\",\n \"contents[].parts[].inlineData.data\": \"<string>\",\n \"generationConfig\": {},\n \"generationConfig.responseModalities\": [\n \"<string>\"\n ],\n \"generationConfig.imageConfig\": {},\n \"generationConfig.imageConfig.aspectRatio\": \"<string>\",\n \"generationConfig.imageConfig.imageSize\": \"<string>\",\n \"safetySettings\": [\n {}\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://www.token-nova.com/v1beta/models/{model}:generateContent")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"contents\": [\n {}\n ],\n \"contents[].role\": \"<string>\",\n \"contents[].parts\": [\n {}\n ],\n \"contents[].parts[].text\": \"<string>\",\n \"contents[].parts[].inlineData\": {},\n \"contents[].parts[].inlineData.mimeType\": \"<string>\",\n \"contents[].parts[].inlineData.data\": \"<string>\",\n \"generationConfig\": {},\n \"generationConfig.responseModalities\": [\n \"<string>\"\n ],\n \"generationConfig.imageConfig\": {},\n \"generationConfig.imageConfig.aspectRatio\": \"<string>\",\n \"generationConfig.imageConfig.imageSize\": \"<string>\",\n \"safetySettings\": [\n {}\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://www.token-nova.com/v1beta/models/{model}:generateContent")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"contents\": [\n {}\n ],\n \"contents[].role\": \"<string>\",\n \"contents[].parts\": [\n {}\n ],\n \"contents[].parts[].text\": \"<string>\",\n \"contents[].parts[].inlineData\": {},\n \"contents[].parts[].inlineData.mimeType\": \"<string>\",\n \"contents[].parts[].inlineData.data\": \"<string>\",\n \"generationConfig\": {},\n \"generationConfig.responseModalities\": [\n \"<string>\"\n ],\n \"generationConfig.imageConfig\": {},\n \"generationConfig.imageConfig.aspectRatio\": \"<string>\",\n \"generationConfig.imageConfig.imageSize\": \"<string>\",\n \"safetySettings\": [\n {}\n ]\n}"
response = http.request(request)
puts response.read_body{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"inlineData": {
"mimeType": "image/png",
"data": "BASE64_OR_URL"
}
}
]
},
"finishReason": "STOP"
}
],
"usageMetadata": {
"promptTokenCount": 123,
"candidatesTokenCount": 456,
"totalTokenCount": 579,
"trafficType": "ON_DEMAND"
},
"modelVersion": "gemini-3-pro-image-preview",
"createTime": "2026-05-21T00:00:00Z"
}
Gemini Image
Gemini Image Generation API
Use POST /v1beta/models/{model}:generateContent to call the Gemini image generation API, covering gemini-3-pro-image-preview, gemini-2.5-flash-image-preview, and gemini-3.1-flash-image-preview in a unified way.
POST
https://www.token-nova.com
/
v1beta
/
models
/
{model}
:generateContent
Gemini Image Generation API
curl --request POST \
--url https://www.token-nova.com/v1beta/models/{model}:generateContent \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"contents": [
{}
],
"contents[].role": "<string>",
"contents[].parts": [
{}
],
"contents[].parts[].text": "<string>",
"contents[].parts[].inlineData": {},
"contents[].parts[].inlineData.mimeType": "<string>",
"contents[].parts[].inlineData.data": "<string>",
"generationConfig": {},
"generationConfig.responseModalities": [
"<string>"
],
"generationConfig.imageConfig": {},
"generationConfig.imageConfig.aspectRatio": "<string>",
"generationConfig.imageConfig.imageSize": "<string>",
"safetySettings": [
{}
]
}
'import requests
url = "https://www.token-nova.com/v1beta/models/{model}:generateContent"
payload = {
"contents": [{}],
"contents[].role": "<string>",
"contents[].parts": [{}],
"contents[].parts[].text": "<string>",
"contents[].parts[].inlineData": {},
"contents[].parts[].inlineData.mimeType": "<string>",
"contents[].parts[].inlineData.data": "<string>",
"generationConfig": {},
"generationConfig.responseModalities": ["<string>"],
"generationConfig.imageConfig": {},
"generationConfig.imageConfig.aspectRatio": "<string>",
"generationConfig.imageConfig.imageSize": "<string>",
"safetySettings": [{}]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
contents: [{}],
'contents[].role': '<string>',
'contents[].parts': [{}],
'contents[].parts[].text': '<string>',
'contents[].parts[].inlineData': {},
'contents[].parts[].inlineData.mimeType': '<string>',
'contents[].parts[].inlineData.data': '<string>',
generationConfig: {},
'generationConfig.responseModalities': ['<string>'],
'generationConfig.imageConfig': {},
'generationConfig.imageConfig.aspectRatio': '<string>',
'generationConfig.imageConfig.imageSize': '<string>',
safetySettings: [{}]
})
};
fetch('https://www.token-nova.com/v1beta/models/{model}:generateContent', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://www.token-nova.com/v1beta/models/{model}:generateContent",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'contents' => [
[
]
],
'contents[].role' => '<string>',
'contents[].parts' => [
[
]
],
'contents[].parts[].text' => '<string>',
'contents[].parts[].inlineData' => [
],
'contents[].parts[].inlineData.mimeType' => '<string>',
'contents[].parts[].inlineData.data' => '<string>',
'generationConfig' => [
],
'generationConfig.responseModalities' => [
'<string>'
],
'generationConfig.imageConfig' => [
],
'generationConfig.imageConfig.aspectRatio' => '<string>',
'generationConfig.imageConfig.imageSize' => '<string>',
'safetySettings' => [
[
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://www.token-nova.com/v1beta/models/{model}:generateContent"
payload := strings.NewReader("{\n \"contents\": [\n {}\n ],\n \"contents[].role\": \"<string>\",\n \"contents[].parts\": [\n {}\n ],\n \"contents[].parts[].text\": \"<string>\",\n \"contents[].parts[].inlineData\": {},\n \"contents[].parts[].inlineData.mimeType\": \"<string>\",\n \"contents[].parts[].inlineData.data\": \"<string>\",\n \"generationConfig\": {},\n \"generationConfig.responseModalities\": [\n \"<string>\"\n ],\n \"generationConfig.imageConfig\": {},\n \"generationConfig.imageConfig.aspectRatio\": \"<string>\",\n \"generationConfig.imageConfig.imageSize\": \"<string>\",\n \"safetySettings\": [\n {}\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://www.token-nova.com/v1beta/models/{model}:generateContent")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"contents\": [\n {}\n ],\n \"contents[].role\": \"<string>\",\n \"contents[].parts\": [\n {}\n ],\n \"contents[].parts[].text\": \"<string>\",\n \"contents[].parts[].inlineData\": {},\n \"contents[].parts[].inlineData.mimeType\": \"<string>\",\n \"contents[].parts[].inlineData.data\": \"<string>\",\n \"generationConfig\": {},\n \"generationConfig.responseModalities\": [\n \"<string>\"\n ],\n \"generationConfig.imageConfig\": {},\n \"generationConfig.imageConfig.aspectRatio\": \"<string>\",\n \"generationConfig.imageConfig.imageSize\": \"<string>\",\n \"safetySettings\": [\n {}\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://www.token-nova.com/v1beta/models/{model}:generateContent")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"contents\": [\n {}\n ],\n \"contents[].role\": \"<string>\",\n \"contents[].parts\": [\n {}\n ],\n \"contents[].parts[].text\": \"<string>\",\n \"contents[].parts[].inlineData\": {},\n \"contents[].parts[].inlineData.mimeType\": \"<string>\",\n \"contents[].parts[].inlineData.data\": \"<string>\",\n \"generationConfig\": {},\n \"generationConfig.responseModalities\": [\n \"<string>\"\n ],\n \"generationConfig.imageConfig\": {},\n \"generationConfig.imageConfig.aspectRatio\": \"<string>\",\n \"generationConfig.imageConfig.imageSize\": \"<string>\",\n \"safetySettings\": [\n {}\n ]\n}"
response = http.request(request)
puts response.read_body{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"inlineData": {
"mimeType": "image/png",
"data": "BASE64_OR_URL"
}
}
]
},
"finishReason": "STOP"
}
],
"usageMetadata": {
"promptTokenCount": 123,
"candidatesTokenCount": 456,
"totalTokenCount": 579,
"trafficType": "ON_DEMAND"
},
"modelVersion": "gemini-3-pro-image-preview",
"createTime": "2026-05-21T00:00:00Z"
}
Gemini Image Generation API
Gemini image models use the officialgenerateContent format for image generation, which is suitable for directly reusing the contents / parts structure.
- The path is
POST /v1beta/models/{model}:generateContent. - Both text-to-image and image-to-image use the same
contents[].parts[]structure. - Reference images are passed in through
parts[].inlineData. - In the plugin,
responseModalitiesrequests bothIMAGEandTEXTby default. - The response may either return
inlineData.dataas Base64 directly, or return an image URL.
Supported models
gemini-3-pro-image-previewgemini-2.5-flash-image-previewgemini-3.1-flash-image-preview
Model differences
| Model | imageSize behavior | Description |
|---|---|---|
gemini-3-pro-image-preview | Supports 1K, 2K, 4K | Delivers according to the requested imageSize |
gemini-2.5-flash-image-preview | Supports 1K, 2K, 4K | Delivers according to the requested imageSize |
gemini-3.1-flash-image-preview | Supports 1K, 2K, 4K | Delivers according to the requested imageSize |
First understand image-to-image
Gemini does not provide a separate “edit API” here. Image-to-image means directly placing the reference image intocontents[].parts[] as input.
The simplest way to understand it is:
- Text-to-image:
parts[]contains only text - Image-to-image:
parts[]contains both text and images
Text-to-image vs image-to-image
| Scenario | parts[] content | Description |
|---|---|---|
| Text-to-image | Only text | Pure prompt-based generation |
| Image-to-image | text + one or more inlineData | Let the model refer to an existing image’s style, subject, or composition |
How to pass image-to-image
You only need to remember one rule:- The first type of content is the prompt:
{ "text": "..." } - The second type of content is the reference image:
{ "inlineData": { "mimeType": "...", "data": "BASE64..." } }
- Put the
promptfirst - Then convert each reference image to Base64
- Append them one by one to the same
parts[]
Minimal image-to-image example
{
"contents": [
{
"role": "user",
"parts": [
{ "text": "Keep the subject and atmosphere of the reference image, and remake it into a more premium poster" },
{
"inlineData": {
"mimeType": "image/jpeg",
"data": "BASE64_IMAGE"
}
}
]
}
],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"imageConfig": {
"aspectRatio": "16:9",
"imageSize": "2K"
}
}
}
Method and path
POST /v1beta/models/{model}:generateContent
Request example
curl -X POST https://www.token-nova.com/v1beta/models/gemini-3-pro-image-preview:generateContent \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{
"role": "user",
"parts": [
{ "text": "A futuristic AI workstation scene, cool-toned atmosphere, cinematic lighting" }
]
}
],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"temperature": 1.0,
"topP": 0.95,
"maxOutputTokens": 8192,
"imageConfig": {
"aspectRatio": "16:9",
"imageSize": "2K"
}
}
}'
import requests
resp = requests.post(
"https://www.token-nova.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
headers={
"Authorization": "Bearer YOUR_API_KEY",
"Accept": "application/json",
"Content-Type": "application/json",
},
json={
"contents": [
{
"role": "user",
"parts": [
{"text": "A futuristic AI workstation scene, cool-toned atmosphere, cinematic lighting"}
],
}
],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"temperature": 1.0,
"topP": 0.95,
"maxOutputTokens": 8192,
"imageConfig": {
"aspectRatio": "16:9",
"imageSize": "2K",
},
},
},
timeout=60,
)
print(resp.json())
const response = await fetch(
"https://www.token-nova.com/v1beta/models/gemini-3-pro-image-preview:generateContent",
{
method: "POST",
headers: {
Authorization: "Bearer YOUR_API_KEY",
Accept: "application/json",
"Content-Type": "application/json",
},
body: JSON.stringify({
contents: [
{
role: "user",
parts: [{ text: "A futuristic AI workstation scene, cool-toned atmosphere, cinematic lighting" }],
},
],
generationConfig: {
responseModalities: ["TEXT", "IMAGE"],
temperature: 1.0,
topP: 0.95,
maxOutputTokens: 8192,
imageConfig: {
aspectRatio: "16:9",
imageSize: "2K",
},
},
}),
}
);
console.log(await response.json());
Image-to-image example
{
"contents": [
{
"role": "user",
"parts": [
{ "text": "Blend the style of the reference images and output a high-resolution landscape poster" },
{
"inlineData": {
"mimeType": "image/jpeg",
"data": "BASE64_IMAGE_1"
}
},
{
"inlineData": {
"mimeType": "image/jpeg",
"data": "BASE64_IMAGE_2"
}
}
]
}
],
"generationConfig": {
"responseModalities": ["TEXT", "IMAGE"],
"imageConfig": {
"aspectRatio": "16:9",
"imageSize": "2K"
}
}
}
Image-to-image field explanations
| Field | Role in image-to-image |
|---|---|
parts[].text | Tells the model how to modify, what to keep, and what style to output |
parts[].inlineData.mimeType | Declares the reference image format |
parts[].inlineData.data | Base64 content of the reference image |
imageConfig.aspectRatio | Constrains the final image ratio |
imageConfig.imageSize | Constrains the final image resolution |
How many reference images can be passed
From your existingmain.py implementation, the plugin iterates over reference_images and appends each image to parts[], so the documentation can be understood as:
- Supports 1 reference image
- Also supports multiple reference images
- When there are multiple images, they are appended consecutively as multiple
inlineDataentries
How to inspect the result after the response
The image returned by Gemini image generation is usually located at:candidates[0].content.parts[].inlineData.data
- Base64 image data directly
- An image URL directly
BASE64_OR_URL is written intentionally in the documentation.
Body
array<object>
required
Input content list. Each item usually contains
role and parts.string
Role field. The plugin always uses
user.array<object>
required
Array of content fragments. Both the prompt and reference images are built here.
string
Text prompt.
object
Reference image input. Contains two fields:
mimeType and data.string
Image MIME type. Common values are
image/jpeg, image/png, and image/webp.string
Base64-encoded image content.
object
required
Generation configuration object.
array<string>
Return modality list. The plugin uses
["IMAGE", "TEXT"] by default.object
required
Image configuration object.
string
Image ratio. The plugin supports
1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, and 21:9.string
Image resolution. All models support
1K, 2K, and 4K, and will deliver according to the requested imageSize.array<object>
Safety settings. Optional.
Response example
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"inlineData": {
"mimeType": "image/png",
"data": "BASE64_OR_URL"
}
}
]
},
"finishReason": "STOP"
}
],
"usageMetadata": {
"promptTokenCount": 123,
"candidatesTokenCount": 456,
"totalTokenCount": 579,
"trafficType": "ON_DEMAND"
},
"modelVersion": "gemini-3-pro-image-preview",
"createTime": "2026-05-21T00:00:00Z"
}
Response
string
Returned image MIME type.
string
Image data. May be Base64, or may directly be an image URL.
object
Token usage statistics.
