استخدام نماذج صور Gemini

يوضح هذا الدليل كيفية استخدام نماذج صور Gemini عبر CometAPI باستخدام Google Gen AI SDK. ويغطي ما يلي:

إنشاء الصور من النص
تحرير الصور من صورة إلى صورة
تركيب عدة صور
حفظ الصور المُنشأة

Base URL: https://api.cometapi.com
ثبّت SDK: pip install google-genai (Python) أو npm install @google/genai (Node.js)

الإعداد

هيّئ العميل باستخدام Base URL الخاص بـ CometAPI:

from google import genai
from google.genai import types
import os

COMETAPI_KEY = os.environ["COMETAPI_KEY"]

client = genai.Client(
    http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
    api_key=COMETAPI_KEY,
)

import { GoogleGenAI } from "@google/genai";

const COMETAPI_KEY = process.env.COMETAPI_KEY;

const ai = new GoogleGenAI({
  apiKey: COMETAPI_KEY,
  httpOptions: { apiVersion: "v1beta", baseUrl: "https://api.cometapi.com" },
});

package main

import (
	"context"
	"os"
	"google.golang.org/genai"
)

func main() {
	ctx := context.Background()
	apiKey := os.Getenv("COMETAPI_KEY")

	client, _ := genai.NewClient(ctx, &genai.ClientConfig{
		APIKey:  apiKey,
		Backend: genai.BackendGeminiAPI,
		HTTPOptions: genai.HTTPOptions{
			BaseURL: "https://api.cometapi.com",
		},
	})
	// use client below...
}

توليد الصور من النص

أنشئ صورة من Prompt نصي واحفظها في ملف.

from google import genai
from google.genai import types
from PIL import Image
import os

client = genai.Client(
    http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
    api_key=os.environ.get("COMETAPI_KEY"),
)

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents="Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
    ),
)

final_image = None
for part in response.parts:
    if getattr(part, "thought", False):
        continue
    if part.text is not None:
        print(part.text)
    elif part.inline_data is not None:
        final_image = part.as_image()

if final_image:
    final_image.save("generated_image.png")
    print("Image saved to generated_image.png")

import { GoogleGenAI } from "@google/genai";
import * as fs from "fs";

const ai = new GoogleGenAI({
  apiKey: process.env.COMETAPI_KEY,
  httpOptions: { apiVersion: "v1beta", baseUrl: "https://api.cometapi.com" },
});

const response = await ai.models.generateContent({
  model: "gemini-3.1-flash-image-preview",
  contents: "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
  config: { responseModalities: ["TEXT", "IMAGE"] },
});

let finalImagePart;
for (const part of response.candidates[0].content.parts) {
  if (part.thought === true) {
    continue;
  }
  if (part.text) {
    console.log(part.text);
  }
  if (part.inlineData) {
    finalImagePart = part;
  }
}

if (finalImagePart) {
  const buffer = Buffer.from(finalImagePart.inlineData.data, "base64");
  fs.writeFileSync("generated_image.png", buffer);
  console.log("Image saved to generated_image.png");
}

curl -s -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme"}]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"]
    }
  }'

احفظ جزء الصورة النهائي: توجد بيانات الصورة في candidates[0].content.parts، والتي قد تحتوي على أجزاء نصية و/أو أجزاء صور. يمكن لنماذج صور Gemini أيضًا إرجاع أجزاء thought وسيطة قبل الصورة النهائية، خاصةً عند طلب كل من النصوص والصور أو عند تمكين مخرجات التفكير صراحةً. لا تحفظ أول inlineData بشكل أعمى؛ تخطَّ الأجزاء التي يكون فيها thought مساويًا لـ true، ثم احفظ آخر جزء صورة متبقٍّ. استجابة نموذجية تحتوي على الصورة النهائية فقط:

{
  "candidates": [{
    "content": {
      "parts": [
        { "text": "Here is your image..." },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "<base64-encoded-image>"
          }
        }
      ]
    }
  }]
}

استجابة تحتوي على جزء نصي، وصورة thought وسيطة، والصورة النهائية:

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [
        { "text": "Here is your image..." },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "<base64-encoded-intermediate-image>"
          },
          "thought": true
        },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "<base64-encoded-final-image>"
          },
          "thought": false,
          "thoughtSignature": "<signature>"
        }
      ]
    },
    "finishReason": "STOP"
  }]
}

استخدم قاعدة التحليل هذه لكل استجابة صورة من Gemini:

const imageParts = response.candidates[0].content.parts.filter(
  (part) => part.inlineData && part.thought !== true,
);
const finalImagePart = imageParts.at(-1);

توليد صورة إلى صورة

حمّل صورة إدخال وحوّلها باستخدام Prompt نصي.

from google import genai
from google.genai import types
from PIL import Image
import os

client = genai.Client(
    http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
    api_key=os.environ.get("COMETAPI_KEY"),
)

# Load the source image
source_image = Image.open("source.jpg")

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Transform this into a watercolor painting", source_image],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
    ),
)

final_image = None
for part in response.parts:
    if getattr(part, "thought", False):
        continue
    if part.text is not None:
        print(part.text)
    elif part.inline_data is not None:
        final_image = part.as_image()

if final_image:
    final_image.save("watercolor_output.png")

import { GoogleGenAI } from "@google/genai";
import * as fs from "fs";

const ai = new GoogleGenAI({
  apiKey: process.env.COMETAPI_KEY,
  httpOptions: { apiVersion: "v1beta", baseUrl: "https://api.cometapi.com" },
});

const imageData = fs.readFileSync("source.jpg").toString("base64");

const response = await ai.models.generateContent({
  model: "gemini-3.1-flash-image-preview",
  contents: [
    { text: "Transform this into a watercolor painting" },
    { inlineData: { mimeType: "image/jpeg", data: imageData } },
  ],
  config: { responseModalities: ["TEXT", "IMAGE"] },
});

const imageParts = response.candidates[0].content.parts.filter(
  (part) => part.inlineData && part.thought !== true,
);
const finalImagePart = imageParts.at(-1);

if (finalImagePart) {
  fs.writeFileSync("watercolor_output.png", Buffer.from(finalImagePart.inlineData.data, "base64"));
}

curl -s -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [
        { "text": "Transform this into a watercolor painting" },
        { "inline_data": { "mime_type": "image/jpeg", "data": "<base64-encoded-source-image>" } }
      ]
    }],
    "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
  }'

تقبل Python SDK كائنات PIL.Image مباشرةً — ولا حاجة إلى ترميز Base64 يدويًا.
لا تُضمّن البادئة data:image/jpeg;base64, عند تمرير سلاسل Base64 الخام.

تركيب صور متعددة

أنشئ صورة جديدة من عدة صور إدخال. يدعم CometAPI نهجين:

الطريقة 1: صورة كولاج واحدة

اجمع عدة صور مصدر في صورة كولاج واحدة، ثم صف المخرجات المطلوبة.

from google import genai
from google.genai import types
from PIL import Image
import os

client = genai.Client(
    http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
    api_key=os.environ.get("COMETAPI_KEY"),
)

collage = Image.open("collage.jpg")

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=[
        "A model is posing and leaning against a pink BMW with a green alien keychain attached to a pink handbag, a pink parrot on her shoulder, and a pug wearing a pink collar and gold headphones",
        collage,
    ],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
    ),
)

final_image = None
for part in response.parts:
    if getattr(part, "thought", False):
        continue
    if part.inline_data is not None:
        final_image = part.as_image()

if final_image:
    final_image.save("composition_output.png")

curl -s -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [
        { "text": "A model is posing and leaning against a pink BMW with a green alien keychain attached to a pink handbag, a pink parrot on her shoulder, and a pug wearing a pink collar and gold headphones" },
        { "inline_data": { "mime_type": "image/jpeg", "data": "<base64-encoded-collage-image>" } }
      ]
    }],
    "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
  }'

الطريقة 2: عدة صور منفصلة (حتى 14)

مرّر عدة صور مباشرة. تدعم نماذج Gemini 3 حتى 14 صورة مرجعية (عناصر + شخصيات):

from google import genai
from google.genai import types
from PIL import Image
import os

client = genai.Client(
    http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
    api_key=os.environ.get("COMETAPI_KEY"),
)

image1 = Image.open("image1.jpg")
image2 = Image.open("image2.jpg")
image3 = Image.open("image3.jpg")

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents=["Merge the three images", image1, image2, image3],
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
    ),
)

final_image = None
for part in response.parts:
    if getattr(part, "thought", False):
        continue
    if part.inline_data is not None:
        final_image = part.as_image()

if final_image:
    final_image.save("merged_output.png")

curl -s -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [
        { "text": "Merge the three images" },
        { "inline_data": { "mime_type": "image/jpeg", "data": "<base64-image-1>" } },
        { "inline_data": { "mime_type": "image/jpeg", "data": "<base64-image-2>" } },
        { "inline_data": { "mime_type": "image/jpeg", "data": "<base64-image-3>" } }
      ]
    }],
    "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
  }'

توليد صور 4K

حدّد image_config باستخدام aspect_ratio وimage_size للحصول على مخرجات عالية الدقة:

from google import genai
from google.genai import types
import os

client = genai.Client(
    http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
    api_key=os.environ.get("COMETAPI_KEY"),
)

response = client.models.generate_content(
    model="gemini-3.1-flash-image-preview",
    contents="Da Vinci style anatomical sketch of a Monarch butterfly on textured parchment",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
        image_config=types.ImageConfig(
            aspect_ratio="1:1",
            image_size="4K",
        ),
    ),
)

final_image = None
for part in response.parts:
    if getattr(part, "thought", False):
        continue
    if part.text is not None:
        print(part.text)
    elif image := part.as_image():
        final_image = image

if final_image:
    final_image.save("butterfly_4k.png")

import { GoogleGenAI } from "@google/genai";
import * as fs from "fs";

const ai = new GoogleGenAI({
  apiKey: process.env.COMETAPI_KEY,
  httpOptions: { apiVersion: "v1beta", baseUrl: "https://api.cometapi.com" },
});

const response = await ai.models.generateContent({
  model: "gemini-3.1-flash-image-preview",
  contents: "Da Vinci style anatomical sketch of a Monarch butterfly on textured parchment",
  config: {
    responseModalities: ["TEXT", "IMAGE"],
    imageConfig: { aspectRatio: "1:1", imageSize: "4K" },
  },
});

const imageParts = response.candidates[0].content.parts.filter(
  (part) => part.inlineData && part.thought !== true,
);
const finalImagePart = imageParts.at(-1);

if (finalImagePart) {
  fs.writeFileSync("butterfly_4k.png", Buffer.from(finalImagePart.inlineData.data, "base64"));
}

curl -s -X POST \
  "https://api.cometapi.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Da Vinci style anatomical sketch of a Monarch butterfly on textured parchment"}]}],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "1:1", "imageSize": "4K"}
    }
  }'

بالنسبة إلى الطلبات عالية الدقة، قيّم المخرجات بالاعتماد على جزء الصورة النهائي غير المصنّف كـ thought. إذا كان التكامل لديك يحفظ أول جزء inlineData، فقد يحفظ صورة thought وسيطة بدقة أقل من imageSize المطلوب.

تحرير الصور متعدد الأدوار (الدردشة)

استخدم ميزة الدردشة في SDK لتحسين الصور بشكل تكراري:

from google import genai
from google.genai import types
import os

client = genai.Client(
    http_options={"api_version": "v1beta", "base_url": "https://api.cometapi.com"},
    api_key=os.environ.get("COMETAPI_KEY"),
)

chat = client.chats.create(
    model="gemini-3.1-flash-image-preview",
    config=types.GenerateContentConfig(
        response_modalities=["TEXT", "IMAGE"],
    ),
)

## First turn: Generate
response = chat.send_message(
    "Create a vibrant infographic explaining photosynthesis as a recipe, styled like a colorful kids cookbook"
)

final_image = None
for part in response.parts:
    if getattr(part, "thought", False):
        continue
    if part.text is not None:
        print(part.text)
    elif image := part.as_image():
        final_image = image

if final_image:
    final_image.save("photosynthesis.png")

الجولة الثانية: تحسين

response = chat.send_message(“حدّث هذا الإنفوجرافيك ليكون باللغة الإسبانية. لا تغيّر أي عناصر أخرى.”)

final_image = None
for part in response.parts:
if getattr(part, “thought”, False):
continue
if part.text is not None:
print(part.text)
elif image := part.as_image():
final_image = image

if final_image:
final_image.save(“photosynthesis_spanish.png”)

```javascript Node.js
import { GoogleGenAI } from "@google/genai";
import * as fs from "fs";

const ai = new GoogleGenAI({
  apiKey: process.env.COMETAPI_KEY,
  httpOptions: { apiVersion: "v1beta", baseUrl: "https://api.cometapi.com" },
});

const chat = ai.chats.create({
  model: "gemini-3.1-flash-image-preview",
  config: { responseModalities: ["TEXT", "IMAGE"] },
});

// First turn: generate
const response1 = await chat.sendMessage(
  "Create a vibrant infographic explaining photosynthesis as a recipe, styled like a colorful kids cookbook"
);
const imageParts1 = response1.candidates[0].content.parts.filter(
  (part) => part.inlineData && part.thought !== true,
);
const finalImagePart1 = imageParts1.at(-1);
if (finalImagePart1) {
  fs.writeFileSync("photosynthesis.png", Buffer.from(finalImagePart1.inlineData.data, "base64"));
}

// Second turn: refine
const response2 = await chat.sendMessage(
  "Update this infographic to be in Spanish. Do not change any other elements."
);
const imageParts2 = response2.candidates[0].content.parts.filter(
  (part) => part.inlineData && part.thought !== true,
);
const finalImagePart2 = imageParts2.at(-1);
if (finalImagePart2) {
  fs.writeFileSync("photosynthesis_spanish.png", Buffer.from(finalImagePart2.inlineData.data, "base64"));
}

نصائح

تحسين Prompt

حدّد كلمات مفتاحية للأسلوب (مثل “cyberpunk, film grain, low contrast”)، ونسبة الأبعاد، والموضوع، والخلفية، والإضاءة، ومستوى التفاصيل.

تنسيق Base64

عند استخدام HTTP الخام، لا تُضمّن البادئة data:image/png;base64, — استخدم فقط سلسلة Base64 الخام. يتولى Python SDK هذا تلقائيًا باستخدام كائنات PIL.Image.

فرض إخراج الصورة

اضبط "responseModalities" على ["IMAGE"] فقط لضمان إخراج صورة من دون نص.

لماذا تبدو صورتي ضبابية أو بدقة أقل؟

تحقق مما إذا كان الكود الخاص بك قد حفظ صورة تفكير وسيطة. قد تتضمن استجابات صور Gemini أجزاء صور يكون فيها thought مساويًا لـ true؛ وهذه ليست المخرجات النهائية. تخطَّ الأجزاء التي فيها thought: true واحفظ آخر جزء صورة يوجد فيه inlineData ولا يكون thought فيه مساويًا لـ true. إذا لم تكن بحاجة إلى إخراج نصي، فاطلب "responseModalities": ["IMAGE"] لتقليل التعامل مع الاستجابات المختلطة من نص/صورة.

لمزيد من التفاصيل، راجع مرجع API. الوثائق الرسمية: إنشاء الصور باستخدام Nano Banana

فهم الصور في Gemini

الإشراف على المحتوى

مفاتيح API

استخدام نماذج صور Gemini

الإعداد

توليد الصور من النص

توليد صورة إلى صورة

تركيب صور متعددة

الطريقة 1: صورة كولاج واحدة

الطريقة 2: عدة صور منفصلة (حتى 14)

توليد صور 4K

تحرير الصور متعدد الأدوار (الدردشة)

نصائح

​الإعداد

​توليد الصور من النص

​توليد صورة إلى صورة

​تركيب صور متعددة

​الطريقة 1: صورة كولاج واحدة

​الطريقة 2: عدة صور منفصلة (حتى 14)

​توليد صور 4K

​تحرير الصور متعدد الأدوار (الدردشة)

​نصائح

الإعداد

توليد الصور من النص

توليد صورة إلى صورة

تركيب صور متعددة

الطريقة 1: صورة كولاج واحدة

الطريقة 2: عدة صور منفصلة (حتى 14)

توليد صور 4K

تحرير الصور متعدد الأدوار (الدردشة)

نصائح