API Embeddings

Embedding adalah fitur untuk mengubah teks ke dalam bentuk vektor numerik yang digunakan pada semantic search (pencarian berbasis makna), retrieval-augmented generation (RAG), sistem rekomendasi, dan clustering (pengelompokan data).

Endpoint

POST /v1/embeddings

Base URL:

https://api.lunos.tech/v1

Autentikasi

Sertakan API Key Anda pada header Authorization:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
X-App-ID: optional-app-name

Request Body

Contoh Request

curl https://api.lunos.tech/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LUNOS_API_KEY" \
  -d '{
    "model": "openai/text-embedding-3-small",
    "input": "Masukkan teks Anda di sini",
    "encoding_format": "float"
  }'

import requests

response = requests.post(
    "https://api.lunos.tech/v1/embeddings",
    headers={
        "Authorization": "Bearer " + LUNOS_API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "model": "openai/text-embedding-3-small",
        "input": "Masukkan teks Anda di sini",
        "encoding_format": "float",
    },
    timeout=60,
)

result = response.json()
print(result["data"][0]["embedding"])

const response = await fetch("https://api.lunos.tech/v1/embeddings", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LUNOS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/text-embedding-3-small",
    input: "Masukkan teks Anda di sini",
    encoding_format: "float",
  }),
});

const result = await response.json();
console.log(result.data[0].embedding);

<?php

$payload = [
    "model" => "openai/text-embedding-3-small",
    "input" => "Masukkan teks Anda di sini",
    "encoding_format" => "float",
];

$ch = curl_init("https://api.lunos.tech/v1/embeddings");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("LUNOS_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result["data"][0]["embedding"]);

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	payload := map[string]any{
		"model":           "openai/text-embedding-3-small",
		"input":           "Masukkan teks Anda di sini",
		"encoding_format": "float",
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", "https://api.lunos.tech/v1/embeddings", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("LUNOS_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()

	var result map[string]any
	_ = json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result["data"])
}

Contoh Response

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [-0.0069, -0.0053, -0.00004, -0.0240]
    }
  ],
  "model": "openai/text-embedding-3-small",
  "usage": {
    "prompt_tokens": 5,
    "total_tokens": 5
  }
}

Panduan Memilih Model

• Gunakan openai/text-embedding-3-small sebagai pilihan default yang sangat hemat biaya.
• Gunakan openai/text-embedding-3-large apabila Anda membutuhkan kualitas retrieval teks yang lebih tinggi dan presisi.
• Pastikan Anda selalu menggunakan nilai dimensi embedding yang konsisten di dalam satu indeks vector database yang sama.

Dimensi (Dimensions)

Anda bisa menggunakan parameter dimensions untuk memperkecil ukuran vektor yang dihasilkan, sehingga biaya penyimpanan (storage) dan komputasi query menjadi lebih hemat.

{
  "model": "openai/text-embedding-3-large",
  "input": "Testing 123",
  "dimensions": 1024
}

Alur RAG / Retrieval pada Umumnya

1. Potong dokumen Anda menjadi bagian-bagian yang lebih kecil (chunking).
2. Lakukan generate embedding untuk setiap potongan teks tersebut.
3. Simpan hasil vektor beserta metadatanya di dalam vector database pilihan Anda.
4. Saat user melakukan pencarian, ubah teks query tersebut menjadi embedding.
5. Cari potongan teks yang memiliki kemiripan makna tertinggi (cosine similarity) dari database.
6. Kirim konteks yang relevan tersebut ke dalam permintaan /v1/chat/completions untuk menghasilkan jawaban.

Kode Error

• 400 (Bad Request): Format body request salah, ID model tidak valid, atau format embedding tidak didukung.
• 402 (Payment Required): Saldo Anda tidak mencukupi untuk melakukan pemanggilan.
• 500 (Internal Server Error): Terjadi masalah pada sisi Lunos atau provider model asli.

Referensi Lainnya

• Ikhtisar API
• API Model
• API Saldo