Lunos logoLunos
DokumentasiIntegrasi

Ikhtisar Multimodal

Lunos mendukung request yang bersifat multimodal khusus untuk model AI yang mampu memproses input di luar format teks. Anda dapat menyisipkan dan menggabungkan perintah teks dengan file gambar, dokumen PDF, rekaman audio, ataupun video ke dalam satu request yang sama melalui jalur API Chat reguler.

Sebagai catatan tambahan: untuk menghasilkan gambar (output generation), silakan gunakan endpoint khusus generasi gambar.

Kapan Saya Harus Menggunakan Multimodal?

  • Menganalisis gambar foto produk atau hasil screenshot (tangkapan layar).
  • Membaca dan mengekstrak dokumen panjang atau berkas hasil pindaian (scan).
  • Melakukan transkripsi teks atau menganalisis isi rekaman suara/audio.
  • Memahami konteks adegan, peristiwa penting, maupun runutan waktu di dalam file video.

Pola Penggunaan Endpoint Utama

Sebagian besar request multimodal menggunakan endpoint berikut ini:

POST /v1/chat/completions

Pada body request tersebut, parameter messages digunakan, di mana setiap message dapat memiliki properti content berbentuk array yang berisikan beberapa blok jenis konten.

Tipe Blok Konten Umum

  • text
  • image_url
  • file (untuk PDF)
  • input_audio
  • video_url

Perbedaan Input Multimodal vs API Generasi

  • Gunakan endpoint POST /v1/chat/completions apabila Anda ingin model menganalisis/memahami file yang sudah ada (memasukkan gambar/PDF/audio/video).
  • Gunakan endpoint POST /v1/images/generations hanya ketika Anda ingin model menghasilkan gambar visual baru dari sebuah prompt teks.

Contoh Request Input Campuran

curl -X POST "https://api.lunos.tech/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Tolong buatkan ringkasan dari informasi utama yang terdapat pada file dan gambar ini." },
          { "type": "file", "file": { "url": "https://example.com/report.pdf" } },
          { "type": "image_url", "image_url": { "url": "https://example.com/diagram.png" } }
        ]
      }
    ]
  }'

import requests

payload = {
    "model": "google/gemini-2.5-flash",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Tolong buatkan ringkasan dari informasi utama yang terdapat pada file dan gambar ini."},
                {"type": "file", "file": {"url": "https://example.com/report.pdf"}},
                {"type": "image_url", "image_url": {"url": "https://example.com/diagram.png"}},
            ],
        }
    ],
}
response = requests.post(
    "https://api.lunos.tech/v1/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_SECRET_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
)
print(response.json())

const response = await fetch("https://api.lunos.tech/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "google/gemini-2.5-flash",
    messages: [
      {
        role: "user",
        content: [
          { type: "text", text: "Tolong buatkan ringkasan dari informasi utama yang terdapat pada file dan gambar ini." },
          { type: "file", file: { url: "https://example.com/report.pdf" } },
          { type: "image_url", image_url: { url: "https://example.com/diagram.png" } },
        ],
      },
    ],
  }),
});
console.log(await response.json());

Kompatibilitas Model

Penting untuk diingat bahwa tidak semua model mendukung seluruh jenis modalitas data. Sebelum Anda mengirimkan data multimodal:

  1. Panggil endpoint GET /v1/models.
  2. Cek nilai properti inputModalities pada model yang hendak Anda pilih.
  3. Pastikan Anda hanya mengirim tipe konten (teks, gambar, dll) yang benar-benar didukung.

Penggunaan URL vs Base64

  • Sangat disarankan untuk menggunakan tautan URL bagi file yang bisa diakses publik atau aset berukuran besar.
  • Gunakan format Base64 jika file Anda tersimpan secara lokal atau bersifat sangat privat.
  • Usahakan ukuran payload tetap wajar (tidak terlalu besar) ketika menggunakan metode Base64 untuk menghindari kegagalan request.

Praktik Terbaik (Best Practices)

  • Selalu lakukan validasi terhadap tipe dan ukuran file di backend Anda sebelum meneruskannya ke Lunos.
  • Implementasikan routing model yang dinamis berdasarkan kapabilitasnya (menggunakan atribut inputModalities).
  • Tambahkan mekanisme retry dan fallback untuk mengantisipasi limit (batasan) dari vendor penyedia tertentu.
  • Jangan lupa untuk tetap menyertakan instruksi teks yang detail ke dalam konten agar hasil output model tetap konsisten.

Pelajari Modalitas Lebih Lanjut