{ "openapi": "3.1.0", "info": { "title": "Gemini Image Generation API", "version": "1.0.0" }, "servers": [ { "url": "https://api.cometapi.com" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1beta/models/{model}:generateContent": { "post": { "summary": "Gemini Image Generation", "operationId": "gemini_generates_image", "parameters": [ { "name": "model", "in": "path", "required": true, "description": "The Gemini image model to use. See the [Models page](/overview/models) for current options.", "schema": { "type": "string", "default": "gemini-3.1-flash-image-preview" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contents" ], "properties": { "contents": { "type": "array", "description": "Conversation turns. Each item has a `role` (\"user\" or \"model\") and `parts` array containing text and/or image data.", "items": { "type": "object", "properties": { "role": { "type": "string", "description": "Role of the message sender.", "enum": [ "user", "model" ] }, "parts": { "type": "array", "description": "Content blocks — text prompts and/or inline image data.", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Text content (prompt or instruction)." }, "inline_data": { "type": "object", "description": "Inline image data for image-to-image or multi-image input.", "properties": { "mime_type": { "type": "string", "description": "MIME type of the image.", "enum": [ "image/jpeg", "image/png", "image/webp" ] }, "data": { "type": "string", "description": "Raw Base64-encoded image data. Do not include the `data:image/...;base64,` prefix." } } } } } } } } }, "generationConfig": { "type": "object", "description": "Controls generation behavior — output modalities, image resolution, thinking, etc.", "properties": { "responseModalities": { "type": "array", "description": "Output types to return. Use `[\"TEXT\", \"IMAGE\"]` for mixed output, or `[\"IMAGE\"]` to force image-only output.", "items": { "type": "string", "enum": [ "TEXT", "IMAGE" ] }, "default": [ "TEXT", "IMAGE" ] }, "imageConfig": { "type": "object", "description": "Image output configuration.", "properties": { "aspectRatio": { "type": "string", "description": "All models: `1:1` `2:3` `3:2` `3:4` `4:3` `4:5` `5:4` `9:16` `16:9` `21:9`. Gemini 3.1 Flash also supports `1:4` `4:1` `1:8` `8:1`.", "default": "1:1" }, "imageSize": { "type": "string", "description": "Output resolution. Gemini 3 models only — `gemini-2.5-flash-image` always outputs 1024px. Use uppercase K.", "enum": [ "512px", "1K", "2K", "4K" ], "default": "1K" } } }, "thinkingConfig": { "type": "object", "description": "Controls the Thinking process (Gemini 3 models). Thinking generates interim images before the final output.", "properties": { "thinkingLevel": { "type": "string", "description": "Thinking effort level. Only configurable for `gemini-3.1-flash-image-preview`; `gemini-3-pro-image-preview` always uses high thinking.", "enum": [ "minimal", "high" ], "default": "minimal" }, "includeThoughts": { "type": "boolean", "description": "Whether to include thought parts in the response.", "default": false } } } } }, "tools": { "type": "array", "description": "Optional tools. Pass `[{\"google_search\": {}}]` to enable Google Search grounding for real-time information in generated images.", "items": { "type": "object", "properties": { "google_search": { "type": "object", "description": "Enables Google Search grounding." } } } } } }, "examples": { "text-to-image": { "summary": "Text to Image", "value": { "contents": [ { "role": "user", "parts": [ { "text": "A Monarch butterfly anatomical sketch on textured parchment, Da Vinci style" } ] } ], "generationConfig": { "responseModalities": [ "TEXT", "IMAGE" ], "imageConfig": { "aspectRatio": "1:1", "imageSize": "4K" } } } }, "image-to-image": { "summary": "Image to Image", "value": { "contents": [ { "role": "user", "parts": [ { "text": "Transform this into a watercolor painting" }, { "inline_data": { "mime_type": "image/jpeg", "data": "" } } ] } ], "generationConfig": { "responseModalities": [ "TEXT", "IMAGE" ] } } }, "multi-image-composition": { "summary": "Multi-Image Composition", "value": { "contents": [ { "role": "user", "parts": [ { "text": "Blend these images into one scene" }, { "inline_data": { "mime_type": "image/jpeg", "data": "" } }, { "inline_data": { "mime_type": "image/jpeg", "data": "" } } ] } ], "generationConfig": { "responseModalities": [ "TEXT", "IMAGE" ] } } }, "force-image-only": { "summary": "Force Image Output", "value": { "contents": [ { "role": "user", "parts": [ { "text": "A photo-realistic sunset over the ocean" } ] } ], "generationConfig": { "responseModalities": [ "IMAGE" ], "imageConfig": { "aspectRatio": "16:9", "imageSize": "2K" } } } }, "with-thinking": { "summary": "With Thinking (3.1 Flash)", "value": { "contents": [ { "role": "user", "parts": [ { "text": "A futuristic city inside a glass bottle floating in space" } ] } ], "generationConfig": { "responseModalities": [ "IMAGE" ], "thinkingConfig": { "thinkingLevel": "high", "includeThoughts": true } } } }, "with-search-grounding": { "summary": "With Google Search Grounding", "value": { "contents": [ { "role": "user", "parts": [ { "text": "Visualize the current weather forecast for San Francisco as a chart" } ] } ], "generationConfig": { "responseModalities": [ "TEXT", "IMAGE" ] }, "tools": [ { "google_search": {} } ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "object", "properties": { "role": { "type": "string", "description": "Always `model` for responses." }, "parts": { "type": "array", "description": "Response parts — may contain text, images, intermediate thought images, or a mix of these. Skip image parts where `thought` is `true` when saving the final output.", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Text content from the model." }, "inlineData": { "type": "object", "description": "Generated image data.", "properties": { "mimeType": { "type": "string", "description": "Image MIME type, typically `image/png`." }, "data": { "type": "string", "description": "Base64-encoded image data." } } }, "thought": { "type": "boolean", "description": "Whether this part is an intermediate thought part rather than final user-facing output. Skip generated image parts where this value is `true`." }, "thoughtSignature": { "type": "string", "description": "Provider signature metadata for thought-related response parts. Do not use this as the primary final-image selector; use `thought !== true` and save the last remaining image part." } } } } } }, "finishReason": { "type": "string", "description": "Reason generation stopped.", "enum": [ "STOP", "MAX_TOKENS", "SAFETY", "RECITATION" ] }, "index": { "type": "integer" }, "safetyRatings": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string" }, "probability": { "type": "string" } } } } } } }, "usageMetadata": { "type": "object", "properties": { "promptTokenCount": { "type": "integer" }, "candidatesTokenCount": { "type": "integer" }, "totalTokenCount": { "type": "integer" }, "thoughtsTokenCount": { "type": "integer", "description": "Token count for thinking process (Gemini 3 models only)." } } } } } } } } }, "x-codeSamples": [ { "lang": "Python", "label": "Text to Image", "source": "import os\nfrom google import genai\nfrom google.genai import types\n\nclient = genai.Client(\n http_options={\"api_version\": \"v1beta\", \"base_url\": \"https://api.cometapi.com\"},\n api_key=os.environ.get(\"COMETAPI_KEY\"),\n)\n\nresponse = client.models.generate_content(\n model=\"gemini-3.1-flash-lite-image\",\n contents=\"A Monarch butterfly anatomical sketch on textured parchment\",\n config=types.GenerateContentConfig(\n response_modalities=[\"TEXT\", \"IMAGE\"],\n image_config=types.ImageConfig(aspect_ratio=\"1:1\", image_size=\"1K\"),\n ),\n)\n\nfinal_image = None\nfor part in response.parts:\n if getattr(part, \"thought\", False):\n continue\n if part.text:\n print(part.text)\n elif image := part.as_image():\n final_image = image\n\nif final_image:\n final_image.save(\"output.png\")\n" }, { "lang": "Python", "label": "Image to Image", "source": "import os\nfrom google import genai\nfrom google.genai import types\nfrom PIL import Image\n\nclient = genai.Client(\n http_options={\"api_version\": \"v1beta\", \"base_url\": \"https://api.cometapi.com\"},\n api_key=os.environ.get(\"COMETAPI_KEY\"),\n)\n\nsource_image = Image.open(\"source.jpg\")\n\nresponse = client.models.generate_content(\n model=\"gemini-3.1-flash-image\",\n contents=[\"Transform this into a watercolor painting\", source_image],\n config=types.GenerateContentConfig(\n response_modalities=[\"TEXT\", \"IMAGE\"],\n ),\n)\n\nfinal_image = None\nfor part in response.parts:\n if getattr(part, \"thought\", False):\n continue\n if image := part.as_image():\n final_image = image\n\nif final_image:\n final_image.save(\"output.png\")\n" }, { "lang": "Python", "label": "Multi-turn Chat", "source": "import os\nfrom google import genai\nfrom google.genai import types\n\nclient = genai.Client(\n http_options={\"api_version\": \"v1beta\", \"base_url\": \"https://api.cometapi.com\"},\n api_key=os.environ.get(\"COMETAPI_KEY\"),\n)\n\nchat = client.chats.create(\n model=\"gemini-3.1-flash-image\",\n config=types.GenerateContentConfig(\n response_modalities=[\"TEXT\", \"IMAGE\"],\n ),\n)\n\ndef save_final_image(response, path):\n final_image = None\n for part in response.parts:\n if getattr(part, \"thought\", False):\n continue\n if image := part.as_image():\n final_image = image\n if final_image:\n final_image.save(path)\n\n# First turn: generate\nresponse = chat.send_message(\"Create an infographic explaining photosynthesis\")\nsave_final_image(response, \"v1.png\")\n\n# Second turn: refine\nresponse = chat.send_message(\"Translate this to Spanish, keep other elements unchanged\")\nsave_final_image(response, \"v2.png\")\n" }, { "lang": "Python", "label": "With Thinking", "source": "import os\nfrom google import genai\nfrom google.genai import types\n\nclient = genai.Client(\n http_options={\"api_version\": \"v1beta\", \"base_url\": \"https://api.cometapi.com\"},\n api_key=os.environ.get(\"COMETAPI_KEY\"),\n)\n\nresponse = client.models.generate_content(\n model=\"gemini-3.1-flash-image\",\n contents=\"A futuristic city inside a glass bottle floating in space\",\n config=types.GenerateContentConfig(\n response_modalities=[\"IMAGE\"],\n thinking_config=types.ThinkingConfig(\n thinking_level=\"HIGH\",\n include_thoughts=True,\n ),\n ),\n)\n\nfinal_image = None\nfor part in response.parts:\n if getattr(part, \"thought\", False):\n continue\n if image := part.as_image():\n final_image = image\n\nif final_image:\n final_image.save(\"output.png\")\n" }, { "lang": "Python", "label": "With Search Grounding", "source": "import os\nfrom google import genai\nfrom google.genai import types\n\nclient = genai.Client(\n http_options={\"api_version\": \"v1beta\", \"base_url\": \"https://api.cometapi.com\"},\n api_key=os.environ[\"COMETAPI_KEY\"],\n)\n\nresponse = client.models.generate_content(\n model=\"gemini-3.1-flash-image\",\n contents=\"Visualize the current weather in San Francisco as a chart\",\n config=types.GenerateContentConfig(\n response_modalities=[\"TEXT\", \"IMAGE\"],\n tools=[types.Tool(google_search=types.GoogleSearch())],\n ),\n)\n\nfinal_image = None\nfor part in response.parts:\n if getattr(part, \"thought\", False):\n continue\n if image := part.as_image():\n final_image = image\n\nif final_image:\n final_image.save(\"weather.png\")\n" }, { "lang": "Python", "label": "Force Image Only", "source": "import os\nfrom google import genai\nfrom google.genai import types\n\nclient = genai.Client(\n http_options={\"api_version\": \"v1beta\", \"base_url\": \"https://api.cometapi.com\"},\n api_key=os.environ[\"COMETAPI_KEY\"],\n)\n\nresponse = client.models.generate_content(\n model=\"gemini-3-pro-image-preview\",\n contents=\"A photo-realistic sunset over the ocean\",\n config=types.GenerateContentConfig(\n response_modalities=[\"IMAGE\"],\n image_config=types.ImageConfig(aspect_ratio=\"16:9\", image_size=\"2K\"),\n ),\n)\n\nfinal_image = None\nfor part in response.parts:\n if getattr(part, \"thought\", False):\n continue\n if image := part.as_image():\n final_image = image\n\nif final_image:\n final_image.save(\"sunset.png\")\n" }, { "lang": "JavaScript", "label": "Text to Image", "source": "import { GoogleGenAI } from \"@google/genai\";\nimport * as fs from \"fs\";\n\nconst ai = new GoogleGenAI({\n apiKey: process.env.COMETAPI_KEY,\n httpOptions: { apiVersion: \"v1beta\", baseUrl: \"https://api.cometapi.com\" },\n});\n\nconst response = await ai.models.generateContent({\n model: \"gemini-3.1-flash-lite-image\",\n contents: \"A Monarch butterfly anatomical sketch on textured parchment\",\n config: {\n responseModalities: [\"TEXT\", \"IMAGE\"],\n imageConfig: { aspectRatio: \"1:1\", imageSize: \"1K\" },\n },\n});\n\nlet finalImagePart;\nfor (const part of response.candidates[0].content.parts) {\n if (part.thought === true) {\n continue;\n }\n if (part.text) {\n console.log(part.text);\n }\n if (part.inlineData) {\n finalImagePart = part;\n }\n}\n\nif (finalImagePart) {\n fs.writeFileSync(\"output.png\", Buffer.from(finalImagePart.inlineData.data, \"base64\"));\n}\n" }, { "lang": "JavaScript", "label": "Image to Image", "source": "import { GoogleGenAI } from \"@google/genai\";\nimport * as fs from \"fs\";\n\nconst ai = new GoogleGenAI({\n apiKey: process.env.COMETAPI_KEY,\n httpOptions: { apiVersion: \"v1beta\", baseUrl: \"https://api.cometapi.com\" },\n});\n\nconst imageData = fs.readFileSync(\"source.jpg\").toString(\"base64\");\n\nconst response = await ai.models.generateContent({\n model: \"gemini-3.1-flash-image\",\n contents: [\n { text: \"Transform this into a watercolor painting\" },\n { inlineData: { mimeType: \"image/jpeg\", data: imageData } },\n ],\n config: { responseModalities: [\"TEXT\", \"IMAGE\"] },\n});\n\nconst imageParts = response.candidates[0].content.parts.filter(\n (part) => part.inlineData && part.thought !== true,\n);\nconst finalImagePart = imageParts.at(-1);\n\nif (finalImagePart) {\n fs.writeFileSync(\"output.png\", Buffer.from(finalImagePart.inlineData.data, \"base64\"));\n}\n" }, { "lang": "JavaScript", "label": "Multi-turn Chat", "source": "import { GoogleGenAI } from \"@google/genai\";\nimport * as fs from \"fs\";\n\nconst ai = new GoogleGenAI({\n apiKey: process.env.COMETAPI_KEY,\n httpOptions: { apiVersion: \"v1beta\", baseUrl: \"https://api.cometapi.com\" },\n});\n\nconst chat = ai.chats.create({\n model: \"gemini-3.1-flash-image\",\n config: { responseModalities: [\"TEXT\", \"IMAGE\"] },\n});\n\nfunction saveFinalImage(response, path) {\n const imageParts = response.candidates[0].content.parts.filter(\n (part) => part.inlineData && part.thought !== true,\n );\n const finalImagePart = imageParts.at(-1);\n if (finalImagePart) {\n fs.writeFileSync(path, Buffer.from(finalImagePart.inlineData.data, \"base64\"));\n }\n}\n\nconst r1 = await chat.sendMessage(\"Create an infographic explaining photosynthesis\");\nsaveFinalImage(r1, \"v1.png\");\n\nconst r2 = await chat.sendMessage(\"Translate this to Spanish, keep other elements unchanged\");\nsaveFinalImage(r2, \"v2.png\");\n" }, { "lang": "JavaScript", "label": "With Search Grounding", "source": "import { GoogleGenAI } from \"@google/genai\";\nimport fs from \"node:fs\";\n\nconst ai = new GoogleGenAI({\n apiKey: process.env.COMETAPI_KEY,\n httpOptions: { apiVersion: \"v1beta\", baseUrl: \"https://api.cometapi.com\" },\n});\n\nconst response = await ai.models.generateContent({\n model: \"gemini-3.1-flash-image\",\n contents: \"Visualize the current weather in San Francisco as a chart\",\n config: {\n responseModalities: [\"TEXT\", \"IMAGE\"],\n tools: [{ googleSearch: {} }],\n },\n});\n\nconst imageParts = response.candidates[0].content.parts.filter(\n (part) => part.inlineData && part.thought !== true,\n);\nconst finalImagePart = imageParts.at(-1);\n\nif (finalImagePart) {\n fs.writeFileSync(\"weather.png\", Buffer.from(finalImagePart.inlineData.data, \"base64\"));\n}\n" }, { "lang": "JavaScript", "label": "With Thinking", "source": "import { GoogleGenAI } from \"@google/genai\";\nimport fs from \"node:fs\";\n\nconst ai = new GoogleGenAI({\n apiKey: process.env.COMETAPI_KEY,\n httpOptions: { apiVersion: \"v1beta\", baseUrl: \"https://api.cometapi.com\" },\n});\n\nconst response = await ai.models.generateContent({\n model: \"gemini-3.1-flash-image\",\n contents: \"A futuristic city inside a glass bottle floating in space\",\n config: {\n responseModalities: [\"IMAGE\"],\n thinkingConfig: { thinkingLevel: \"HIGH\", includeThoughts: true },\n },\n});\n\nconst imageParts = response.candidates[0].content.parts.filter(\n (part) => part.inlineData && part.thought !== true,\n);\nconst finalImagePart = imageParts.at(-1);\n\nif (finalImagePart) {\n fs.writeFileSync(\"city.png\", Buffer.from(finalImagePart.inlineData.data, \"base64\"));\n}\n" }, { "lang": "JavaScript", "label": "Force Image Only", "source": "import { GoogleGenAI } from \"@google/genai\";\nimport fs from \"node:fs\";\n\nconst ai = new GoogleGenAI({\n apiKey: process.env.COMETAPI_KEY,\n httpOptions: { apiVersion: \"v1beta\", baseUrl: \"https://api.cometapi.com\" },\n});\n\nconst response = await ai.models.generateContent({\n model: \"gemini-3-pro-image-preview\",\n contents: \"A photo-realistic sunset over the ocean\",\n config: {\n responseModalities: [\"IMAGE\"],\n imageConfig: { aspectRatio: \"16:9\", imageSize: \"2K\" },\n },\n});\n\nconst imageParts = response.candidates[0].content.parts.filter(\n (part) => part.inlineData && part.thought !== true,\n);\nconst finalImagePart = imageParts.at(-1);\n\nif (finalImagePart) {\n fs.writeFileSync(\"sunset.png\", Buffer.from(finalImagePart.inlineData.data, \"base64\"));\n}\n" }, { "lang": "Shell", "label": "Text to Image", "source": "curl -s -X POST \\\n \"https://api.cometapi.com/v1beta/models/gemini-3.1-flash-lite-image:generateContent\" \\\n -H \"x-goog-api-key: $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"contents\": [{\"parts\": [{\"text\": \"A Monarch butterfly anatomical sketch on textured parchment\"}]}],\n \"generationConfig\": {\n \"responseModalities\": [\"TEXT\", \"IMAGE\"],\n \"imageConfig\": {\"aspectRatio\": \"1:1\", \"imageSize\": \"1K\"}\n }\n }'\n" }, { "lang": "Shell", "label": "Force Image Only", "source": "curl -s -X POST \\\n \"https://api.cometapi.com/v1beta/models/gemini-3-pro-image-preview:generateContent\" \\\n -H \"x-goog-api-key: $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"contents\": [{\"parts\": [{\"text\": \"A photo-realistic sunset over the ocean\"}]}],\n \"generationConfig\": {\n \"responseModalities\": [\"IMAGE\"],\n \"imageConfig\": {\"aspectRatio\": \"16:9\", \"imageSize\": \"2K\"}\n }\n }'\n" }, { "lang": "Shell", "label": "With Search Grounding", "source": "curl -s -X POST \\\n \"https://api.cometapi.com/v1beta/models/gemini-3.1-flash-image:generateContent\" \\\n -H \"x-goog-api-key: $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"contents\": [{\"parts\": [{\"text\": \"Visualize the current weather in San Francisco as a chart\"}]}],\n \"generationConfig\": {\"responseModalities\": [\"TEXT\", \"IMAGE\"]},\n \"tools\": [{\"google_search\": {}}]\n }'\n" }, { "lang": "Shell", "label": "Image to Image", "source": "curl -s -X POST \\\n \"https://api.cometapi.com/v1beta/models/gemini-3.1-flash-image:generateContent\" \\\n -H \"x-goog-api-key: $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n --data-binary @- <<'EOF'\n{\n \"contents\": [{\n \"parts\": [\n {\"text\": \"Transform this into a watercolor painting\"},\n {\"inlineData\": {\"mimeType\": \"image/jpeg\", \"data\": \"\"}}\n ]\n }],\n \"generationConfig\": {\"responseModalities\": [\"TEXT\", \"IMAGE\"]}\n}\nEOF\n" }, { "lang": "Shell", "label": "Multi-turn Chat", "source": "curl -s -X POST \\\n \"https://api.cometapi.com/v1beta/models/gemini-3.1-flash-image:generateContent\" \\\n -H \"x-goog-api-key: $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"contents\": [\n {\"role\": \"user\", \"parts\": [{\"text\": \"Create an infographic explaining photosynthesis\"}]},\n {\"role\": \"model\", \"parts\": [{\"text\": \"Here is the infographic.\"}]},\n {\"role\": \"user\", \"parts\": [{\"text\": \"Translate this to Spanish, keep other elements unchanged\"}]}\n ],\n \"generationConfig\": {\"responseModalities\": [\"TEXT\", \"IMAGE\"]}\n }'\n" }, { "lang": "Shell", "label": "With Thinking", "source": "curl -s -X POST \\\n \"https://api.cometapi.com/v1beta/models/gemini-3.1-flash-image:generateContent\" \\\n -H \"x-goog-api-key: $COMETAPI_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"contents\": [{\"parts\": [{\"text\": \"A futuristic city inside a glass bottle floating in space\"}]}],\n \"generationConfig\": {\n \"responseModalities\": [\"IMAGE\"],\n \"thinkingConfig\": {\"thinkingLevel\": \"HIGH\", \"includeThoughts\": true}\n }\n }'\n" } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Use your CometAPI API key." } } } }