3 Cara Mengatasi Kegagalan Pengenalan Gambar Gemini pada OpenClaw: Kesalahan Umum Mode Kompatibilitas OpenAI dan Panduan Konfigurasi Format Asli

Menggunakan mode kompatibilitas OpenAI di OpenClaw untuk memanggil model Gemini dalam pengenalan gambar sering kali memicu error. Ini adalah masalah umum bagi banyak pengembang saat mengonfigurasi agen AI multimodal. Artikel ini akan menganalisis secara mendalam penyebab utama error Invalid JSON payload dan memberikan 3 solusi teruji untuk membantu Anda memperbaiki kegagalan pengenalan gambar Gemini di OpenClaw dengan cepat.

Nilai Inti: Setelah membaca artikel ini, Anda akan memahami perbedaan utama antara mode kompatibilitas OpenAI dan API asli Gemini, menguasai metode konfigurasi yang benar, dan menyelesaikan masalah kegagalan pengenalan gambar sepenuhnya.

Fenomena Error Kegagalan Pengenalan Gambar Gemini di OpenClaw

Setelah mengonfigurasi model Gemini di OpenClaw, saat mencoba melakukan pengenalan gambar, log latar belakang biasanya akan menampilkan error tipikal berikut:

Invalid JSON payload received. Unknown name "patternProperties"
at 'tools[0].function_declarations[3].parameters.properties[4].value':
Cannot find field.

Invalid JSON payload received. Unknown name "const"
at 'tools[0].function_declarations[37].parameters.properties[0].value':
Cannot find field.

Karakteristik Utama Error Pengenalan Gambar Gemini di OpenClaw

Diagnosa Cepat Kegagalan Pengenalan Gambar Gemini di OpenClaw

Kesalahpahaman yang umum adalah menganggap kemampuan pengenalan gambar Gemini bermasalah. Faktanya, jika Anda menguji API menggunakan demo pemahaman visual resmi Gemini, fungsi pengenalan gambar berjalan dengan normal. Masalahnya terletak pada ketidakcocokan format saat OpenClaw meneruskan permintaan melalui mode kompatibilitas OpenAI.

Cara verifikasinya sangat mudah:

# Panggil langsung API Gemini untuk menguji pengenalan gambar — Berjalan normal
import google.generativeai as genai
import PIL.Image

genai.configure(api_key="YOUR_GEMINI_API_KEY")
model = genai.GenerativeModel("gemini-2.5-flash")

image = PIL.Image.open("test.jpg")
response = model.generate_content(["Deskripsikan gambar ini", image])
print(response.text)  # ✅ Output deskripsi gambar normal

🎯 Saran Diagnosa: Jika Anda mengalami masalah pengenalan gambar Gemini di OpenClaw, pastikan terlebih dahulu kunci API dan modelnya sendiri tidak bermasalah dengan cara di atas. Anda juga bisa menguji kemampuan pemahaman visual Gemini dengan cepat melalui platform APIYI (apiyi.com), yang secara otomatis akan menangani masalah kompatibilitas format.

Analisis Akar Masalah Kegagalan Pengenalan Gambar Gemini pada OpenClaw

Memahami akar masalah adalah kunci untuk memilih solusi yang paling tepat. Kegagalan OpenClaw dalam melakukan pemanggilan pengenalan gambar pada Gemini disebabkan oleh masalah kompatibilitas JSON Schema.

Perbedaan JSON Schema pada Pemanggilan Alat OpenAI dan Gemini

Saat OpenClaw menggunakan mode kompatibilitas OpenAI (openai-completions) untuk memanggil Gemini, alur permintaannya adalah sebagai berikut:

OpenClaw menyusun permintaan (format OpenAI)
    ↓
Berisi JSON Schema definisi alat
    ↓
Dikirim ke endpoint kompatibilitas OpenAI Gemini
    ↓
Gemini mengurai function_declarations
    ↓
❌ Menemukan bidang Schema yang tidak didukung → Kesalahan 400

Daftar Bidang JSON Schema yang Tidak Didukung oleh Gemini API

Ini adalah inti dari masalahnya. Dukungan Gemini terhadap function_declarations dalam JSON Schema hanyalah subset terbatas. Bidang-bidang berikut akan langsung menyebabkan kesalahan 400:

Mengapa Beralih ke GPT-5.4 Tidak Menimbulkan Masalah

Hal ini semakin memperkuat analisis akar masalah. Saat model di OpenClaw diganti dari Gemini ke GPT-5.4, pengenalan gambar langsung kembali normal—karena API GPT-5.4 secara bawaan mendukung spesifikasi JSON Schema lengkap, sehingga Schema definisi alat yang dihasilkan oleh OpenClaw sepenuhnya kompatibel.

📌 Wawasan Kunci: Ini bukan masalah kemampuan pengenalan gambar Gemini, melainkan ketidakcocokan antara Schema alat yang dikirim oleh mode kompatibilitas OpenAI OpenClaw dengan persyaratan format API Gemini.

Solusi 1: Beralih ke Format Asli Gemini (Direkomendasikan)

Solusi paling tuntas adalah mengubah tipe antarmuka API Gemini di OpenClaw dari openai-completions ke format asli google-generative-ai.

Langkah Konfigurasi

Sebelum diubah (Mode kompatibilitas OpenAI — Bermasalah):

{
  "provider": "google",
  "model": "gemini-2.5-flash",
  "baseUrl": "https://generativelanguage.googleapis.com/v1beta/openai",
  "api": "openai-completions",
  "apiKey": "YOUR_GEMINI_API_KEY"
}

Setelah diubah (Format asli Gemini — Direkomendasikan):

{
  "provider": "google",
  "model": "gemini-2.5-flash",
  "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
  "api": "google-generative-ai",
  "apiKey": "YOUR_GEMINI_API_KEY"
}

Perubahan Inti pada Konfigurasi Format Asli

Beralih Cepat Menggunakan OpenClaw CLI

# Cara 1: Inisialisasi ulang konfigurasi Gemini
openclaw onboard --auth-choice gemini-api-key

# Cara 2: Edit file konfigurasi secara manual
# Lokasi file konfigurasi: ~/.openclaw/config.json
# Ubah kolom api dari "openai-completions" menjadi "google-generative-ai"

{
  "providers": {
    "google": {
      "apiKey": "YOUR_GEMINI_API_KEY",
      "models": {
        "gemini-2.5-flash": {
          "api": "google-generative-ai",
          "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
          "capabilities": {
            "vision": true,
            "functionCalling": true,
            "streaming": true
          },
          "reasoning": false
        },
        "gemini-2.5-pro": {
          "api": "google-generative-ai",
          "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
          "capabilities": {
            "vision": true,
            "functionCalling": true,
            "streaming": true
          },
          "reasoning": true,
          "thinkingBudget": 8192
        }
      }
    }
  }
}

🚀 Mulai Cepat: Jika Anda tidak ingin repot menangani masalah kompatibilitas konfigurasi, disarankan untuk menggunakan antarmuka terpadu dari platform APIYI apiyi.com. Platform akan secara otomatis mengonversi permintaan format OpenAI ke format asli Gemini, sehingga pengembang tidak perlu memusingkan perbedaan Skema.

Solusi 2: Menangani Kompatibilitas Secara Otomatis Melalui Layanan Proksi API

Jika Anda ingin terus menggunakan mode kompatibilitas OpenAI di OpenClaw untuk memanggil berbagai model (termasuk Gemini), Anda dapat mengatasi masalah kompatibilitas format melalui layanan proksi API.

Cara Kerja Layanan Proksi API

OpenClaw (Permintaan format OpenAI)
    ↓
Layanan proksi API (seperti APIYI)
    ↓ Membersihkan bidang JSON Schema yang tidak kompatibel secara otomatis
    ↓ Mengonversi format permintaan secara otomatis
Gemini API (Format asli)
    ↓
✅ Hasil pengenalan gambar dikembalikan dengan normal

Contoh Konfigurasi

# Memanggil pengenalan gambar Gemini melalui layanan proksi APIYI
import openai
import base64

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Antarmuka terpadu APIYI
)

# Membaca gambar dan melakukan encoding
with open("test.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Deskripsikan isi gambar ini"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/jpeg;base64,{image_data}"
                    }
                }
            ]
        }
    ]
)
print(response.choices[0].message.content)

Perbandingan: Layanan Proksi vs Koneksi Langsung

Konfigurasi proksi APIYI di OpenClaw:

{
  "provider": "apiyi",
  "model": "gemini-2.5-flash",
  "baseUrl": "https://api.apiyi.com/v1",
  "api": "openai-completions",
  "apiKey": "YOUR_APIYI_KEY"
}

💡 Saran Pilihan: Jika Anda menggunakan berbagai model di OpenClaw (GPT-5.4, Claude, Gemini, dll.), mengelola pemanggilan API secara terpadu melalui APIYI apiyi.com adalah pilihan yang lebih efisien untuk menghindari konfigurasi format API yang berbeda-beda untuk setiap model.

Solusi 3: Pembersihan Manual Bidang JSON Schema yang Tidak Kompatibel

Jika Anda perlu mengatasi masalah kompatibilitas di tingkat kode, Anda dapat membersihkan bidang JSON Schema yang tidak didukung oleh Gemini secara manual sebelum mengirim permintaan.

Fungsi Pembersihan JSON Schema

def clean_schema_for_gemini(schema: dict) -> dict:
    """Membersihkan bidang JSON Schema yang tidak didukung oleh Gemini"""
    unsupported_keys = {
        "patternProperties",
        "const",
        "additionalProperties",
        "$schema",
        "exclusiveMaximum",
        "exclusiveMinimum",
        "propertyNames",
    }

    if isinstance(schema, dict):
        return {
            k: clean_schema_for_gemini(v)
            for k, v in schema.items()
            if k not in unsupported_keys
        }
    elif isinstance(schema, list):
        return [clean_schema_for_gemini(item) for item in schema]
    return schema

import openai
import json

def clean_schema_for_gemini(schema):
    """Pembersihan rekursif bidang JSON Schema yang tidak didukung oleh Gemini"""
    unsupported_keys = {
        "patternProperties", "const", "additionalProperties",
        "$schema", "exclusiveMaximum", "exclusiveMinimum",
        "propertyNames", "if", "then", "else",
        "allOf", "anyOf", "oneOf", "not",
    }

    if isinstance(schema, dict):
        cleaned = {}
        for k, v in schema.items():
            if k not in unsupported_keys:
                cleaned[k] = clean_schema_for_gemini(v)
        return cleaned
    elif isinstance(schema, list):
        return [clean_schema_for_gemini(item) for item in schema]
    return schema

def clean_tools_for_gemini(tools):
    """Membersihkan semua Schema dalam daftar alat"""
    cleaned_tools = []
    for tool in tools:
        tool_copy = json.loads(json.dumps(tool))
        if "function" in tool_copy:
            params = tool_copy["function"].get("parameters", {})
            tool_copy["function"]["parameters"] = clean_schema_for_gemini(params)
        cleaned_tools.append(tool_copy)
    return cleaned_tools

# Contoh penggunaan
tools = [
    {
        "type": "function",
        "function": {
            "name": "analyze_image",
            "description": "Menganalisis konten gambar",
            "parameters": {
                "type": "object",
                "properties": {
                    "image_url": {"type": "string"},
                    "detail": {"type": "string", "const": "high"}  # Tidak didukung Gemini
                },
                "patternProperties": {"^x-": {"type": "string"}},  # Tidak didukung Gemini
                "additionalProperties": False  # Tidak didukung Gemini
            }
        }
    }
]

# Panggil setelah dibersihkan
cleaned_tools = clean_tools_for_gemini(tools)

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "Halo"}],
    tools=cleaned_tools
)

⚠️ Catatan: Solusi pembersihan Schema secara manual mengharuskan Anda memproses definisi parameter untuk setiap alat, sehingga biaya pemeliharaannya cukup tinggi. Jika jumlah alat banyak atau sering berubah, disarankan untuk memprioritaskan Solusi 1 (format asli) atau Solusi 2 (layanan proksi API).

Perbandingan 3 Solusi dan Saran Pemilihan

Pohon Keputusan Pemilihan

• Hanya menggunakan Gemini di OpenClaw → Solusi 1 (format asli), paling stabil
• Menggunakan berbagai model di OpenClaw → Solusi 2 (proksi APIYI), paling praktis
• Aplikasi AI mandiri yang butuh kontrol presisi → Solusi 3 (pembersihan manual), paling fleksibel
• Tidak yakin pilih yang mana → Coba Solusi 2 terlebih dahulu, verifikasi cepat melalui apiyi.com

Pertanyaan Umum (FAQ)

Kesimpulan

Penyebab utama kegagalan pengenalan gambar Gemini pada OpenClaw adalah ketidakcocokan field JSON Schema dalam mode kompatibilitas OpenAI, bukan karena kemampuan visual model Gemini yang bermasalah. Terdapat 3 solusi yang bisa dipilih sesuai kebutuhan:

• Format Native (google-generative-ai): Paling menyeluruh, direkomendasikan untuk skenario yang hanya menggunakan Gemini.
• Layanan Proksi API: Paling praktis, direkomendasikan untuk skenario penggunaan banyak model sekaligus.
• Pembersihan Schema Manual: Paling fleksibel, direkomendasikan untuk sistem yang dibangun sendiri.

Kami merekomendasikan penggunaan APIYI (apiyi.com) untuk memverifikasi efektivitas pengenalan gambar Gemini dengan cepat. Platform ini mendukung pemanggilan terpadu untuk model-model utama seperti Gemini, GPT, dan Claude, serta menangani perbedaan format API antar model secara otomatis.

Referensi

1. Dokumentasi Resmi Gemini – Pemahaman Gambar: Penjelasan kemampuan pemahaman visual Gemini

   • Tautan: ai.google.dev/gemini-api/docs/image-understanding

2. Dokumentasi Resmi Gemini – Kompatibilitas OpenAI: Penjelasan pemanggilan Gemini menggunakan SDK OpenAI

   • Tautan: ai.google.dev/gemini-api/docs/openai

3. OpenClaw GitHub Issue #21172: Kesalahan 400 pada API Gemini yang disebabkan oleh patternProperties

   • Tautan: github.com/openclaw/openclaw/issues/21172

4. OpenClaw GitHub Issue #14456: Kesalahan 400 pada mode kompatibilitas OpenAI Gemini 2.5 Flash

   • Tautan: github.com/openclaw/openclaw/issues/14456

5. Dokumentasi Konfigurasi Model OpenClaw: Panduan konfigurasi penyedia model

   • Tautan: docs.openclaw.ai/concepts/model-providers

📝 Penulis Artikel: Tim APIYI — Fokus pada integrasi API Model Bahasa Besar AI dan analisis teknis
🔗 Tutorial Lainnya: Kunjungi APIYI di apiyi.com untuk mendapatkan panduan pemanggilan model lainnya dan kuota uji coba gratis