Panduan Vision (Image Understanding)

Selain image generation, KoboiLLM juga mendukung vision models — yaitu model yang bisa “melihat” dan menganalisis gambar yang Anda kirim. Cocok untuk:

• Deskripsi otomatis (alt-text, captioning)
• OCR sederhana / membaca teks di gambar
• Analisis foto produk, screenshot, atau dokumen
• Visual QA — tanya jawab berbasis gambar

API mengikuti standar OpenAI Chat Completions dengan content berbentuk array multimodal, sehingga SDK OpenAI dan LiteLLM yang sudah ada bisa langsung dipakai.

---

Daftar Isi

1. Endpoint dan Otentikasi
2. Model Vision yang Tersedia
3. Quick Start — Kirim Gambar ke Model
4. Mengirim Gambar Lokal (Base64)
5. Multi-Image (Lebih dari Satu Gambar)
6. Parameter detail & format
7. Cek Dukungan Vision di Suatu Model
8. Spec Singkat
9. Tips & Best Practices

---

1. Endpoint dan Otentikasi

Base URL:

https://lite.koboillm.com/v1

Endpoint https://api.koboillm.com/v1 juga tersedia dan identik fungsinya.

Endpoint utama: POST /v1/chat/completions — sama seperti chat biasa, hanya saja field content di pesan user diisi array berisi text dan image_url.

Otentikasi pakai header Authorization: Bearer <API_KEY>. Simpan API key di environment variable, jangan hard-code:

export LITELLM_API_KEY="sk-xxxxxxxxxxxxxx"

---

2. Model Vision yang Tersedia

Model di bawah ini secara native mendukung input gambar di KoboiLLM. Gunakan salah satu nama model di kolom Endpoint name.

Provider	Endpoint name	Cocok untuk
OpenAI	openai/gpt-4o-mini	Vision murah & cepat — rekomendasi default
OpenAI	openai/gpt-4o	Vision dengan kualitas reasoning lebih tinggi
Google Gemini	gemini/gemini-2.5-flash	Vision murah, throughput tinggi
Google Gemini	gemini/gemini-2.5-pro	Vision paling teliti untuk dokumen kompleks / OCR

Daftar model bisa berubah sewaktu-waktu. Untuk daftar paling akurat, cek /v1/models atau dashboard di https://lite.koboillm.com.

---

3. Quick Start — Kirim Gambar ke Model

Contoh paling sederhana: kirim URL gambar dan tanya “Apa isi gambar ini?“.

3.1 — curl

curl -X POST https://lite.koboillm.com/v1/chat/completions \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Apa isi gambar ini?" },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://docs.koboillm.com/koboi_llm_logo.png"
            }
          }
        ]
      }
    ]
  }'

3.2 — Python (OpenAI SDK)

LiteLLM proxy bersifat OpenAI-compatible, jadi SDK OpenAI standar bekerja dengan mengganti base_url.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://lite.koboillm.com/v1",
    api_key=os.environ["LITELLM_API_KEY"],
)

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",   # ganti ke openai/gpt-4o atau gemini/gemini-2.5-flash
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Apa isi gambar ini?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://docs.koboillm.com/koboi_llm_logo.png"
                    },
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)

3.3 — Python (LiteLLM SDK)

import os
from litellm import completion

os.environ["LITELLM_API_KEY"] = "sk-xxxxxxxxxxxxxx"

response = completion(
    model="openai/gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Apa isi gambar ini?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://docs.koboillm.com/koboi_llm_logo.png"
                    },
                },
            ],
        }
    ],
    api_base="https://lite.koboillm.com/v1",
    api_key=os.environ["LITELLM_API_KEY"],
)

print(response.choices[0].message.content)

3.4 — JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://lite.koboillm.com/v1",
  apiKey: process.env.LITELLM_API_KEY,
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Apa isi gambar ini?" },
        {
          type: "image_url",
          image_url: {
            url: "https://docs.koboillm.com/koboi_llm_logo.png",
          },
        },
      ],
    },
  ],
});

console.log(response.choices[0].message.content);

3.5 — Contoh dengan model Gemini

Model Gemini menerima format multimodal yang sama:

response = client.chat.completions.create(
    model="gemini/gemini-2.5-flash",   # atau gemini/gemini-2.5-pro
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Deskripsikan gambar ini dalam 2 kalimat."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://docs.koboillm.com/koboi_llm_logo.png"
                    },
                },
            ],
        }
    ],
)

---

4. Mengirim Gambar Lokal (Base64)

Jika gambar tidak punya URL publik (mis. file dari disk atau hasil upload user), encode ke base64 data URI lalu kirim sebagai image_url.url.

import base64
from openai import OpenAI

client = OpenAI(
    base_url="https://lite.koboillm.com/v1",
    api_key="sk-xxxxxxxxxxxxxx",
)

with open("foto.jpg", "rb") as f:
    b64 = base64.b64encode(f.read()).decode("utf-8")

data_uri = f"data:image/jpeg;base64,{b64}"

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Apa yang sedang terjadi di foto ini?"},
                {"type": "image_url", "image_url": {"url": data_uri}},
            ],
        }
    ],
)

print(response.choices[0].message.content)

Mime-type yang umum: image/jpeg, image/png, image/webp, image/gif. Pastikan prefix data:<mime>;base64, benar sesuai jenis file.

---

5. Multi-Image (Lebih dari Satu Gambar)

Kirim beberapa gambar dalam satu request — model bisa membandingkan, menggabungkan, atau menganalisis berurutan.

response = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Apa perbedaan antara dua gambar ini?"},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/before.jpg"},
                },
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/after.jpg"},
                },
            ],
        }
    ],
)

Setiap gambar tambahan = token input tambahan = biaya tambahan. Gunakan hanya jumlah gambar yang benar-benar diperlukan.

---

6. Parameter detail & format

Field image_url adalah object dengan tiga kemungkinan key:

"image_url": {
  "url": "https://... atau data:image/...;base64,...",
  "detail": "low" | "high" | "auto",   // opsional, OpenAI-only
  "format": "image/jpeg"                // opsional, untuk Gemini/Anthropic/Bedrock
}

• detail (OpenAI saja) — low memakai lebih sedikit token (cocok untuk gambar kecil/thumbnail), high memproses gambar di resolusi penuh. Default auto.
• format — set eksplisit jika URL gambar Anda tidak punya ekstensi atau mime-type yang bisa ditebak (misalnya URL gs://... di Vertex AI, atau signed URL tanpa ekstensi). Akan diabaikan untuk provider yang tidak membutuhkannya (mis. OpenAI).

Contoh — gambar tanpa ekstensi:

response = client.chat.completions.create(
    model="gemini/gemini-2.5-pro",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Baca teks di gambar ini."},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://cdn.example.com/scan-abc123",
                        "format": "image/jpeg",
                    },
                },
            ],
        }
    ],
)

---

7. Cek Dukungan Vision di Suatu Model

Lewat LiteLLM SDK

import litellm

assert litellm.supports_vision(model="openai/gpt-4o-mini") is True
assert litellm.supports_vision(model="gemini/gemini-2.5-flash") is True
assert litellm.supports_vision(model="openai/gpt-3.5-turbo") is False

Lewat endpoint /model_group/info

curl -X GET 'https://lite.koboillm.com/model_group/info' \
  -H 'accept: application/json' \
  -H 'x-api-key: sk-xxxxxxxxxxxxxx'

Cari model yang Anda butuhkan di response, lalu lihat field supports_vision:

{
  "data": [
    {
      "model_group": "openai/gpt-4o-mini",
      "providers": ["openai"],
      "mode": "chat",
      "supports_vision": true,
      "supports_function_calling": true
    }
  ]
}

---

8. Spec Singkat

Format isi content di pesan user:

"content": [
  { "type": "text",      "text": "..." },
  { "type": "image_url", "image_url": "https://..." },           // shortcut
  { "type": "image_url", "image_url": {
      "url":    "https://... atau data:image/...;base64,...",
      "detail": "low" | "high" | "auto",   // OpenAI-only, opsional
      "format": "image/jpeg"                // opsional, mime-type eksplisit
  }}
]

Urutan item dalam array bebas — model membaca semuanya sebagai satu konteks.

---

9. Tips & Best Practices

Pemilihan model

• Captioning umum / alt-text → openai/gpt-4o-mini (paling murah & cepat).
• OCR dokumen, struktur kompleks, tabel → openai/gpt-4o atau gemini/gemini-2.5-pro.
• Volume tinggi, latency penting → gemini/gemini-2.5-flash.

Optimasi biaya

• Gunakan detail: "low" untuk gambar yang tidak butuh resolusi penuh (thumbnail, ikon, screenshot UI sederhana) — hemat token ±5–10×.
• Resize gambar besar di sisi client sebelum dikirim. Gambar 4K dan 1024×1024 biasanya menghasilkan kualitas analisis yang setara untuk task umum.
• Jangan kirim base64 untuk gambar yang sudah punya URL publik — URL lebih ringan (tidak boros bandwidth ke proxy).
• Hindari multi-image jika satu gambar grid/collage sudah cukup.

Akurasi

• Sertakan instruksi yang jelas di text (mis. “Ekstrak hanya nomor invoice dan tanggalnya, output JSON”).
• Untuk OCR teks kecil/padat → pakai detail: "high" (OpenAI) atau model gemini-2.5-pro.
• Jika output harus terstruktur, gabungkan dengan response_format: { "type": "json_object" }.

Privasi & data

• Gambar yang dikirim diteruskan ke provider asli (OpenAI/Google). Jangan upload data sensitif (KTP, dokumen rahasia, dll) tanpa persetujuan pihak bersangkutan.
• Proxy KoboiLLM tidak menyimpan gambar Anda; hanya metadata usage yang dicatat untuk billing.

---

Pertanyaan?

• Status sistem & dashboard: https://lite.koboillm.com
• WhatsApp admin: lihat halaman Pengenalan untuk kontak.
• Untuk request model vision baru, hubungi tim platform.