Mulai dengan Python (SDK OpenAI)

seamless.ai.id kompatibel dengan API OpenAI. Yang berbeda hanya base URL dan API key:

https://api.seamless.ai.id/v1

1. Siapkan API key

Pendaftaran mandiri belum dibuka: minta API key ke operator seamless.ai.id. Isi saldo dari dashboard (QRIS) sebelum memanggil model berbayar. Simpan key di variabel lingkungan, jangan di kode:

export SEAMLESS_API_KEY='sk-seamless-...'

2. Pasang SDK OpenAI

pip install openai

Setiap program di halaman ini dijalankan otomatis terhadap gateway dengan SDK openai 3.40.0.

3. Panggilan pertama

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.seamless.ai.id/v1",
    api_key=os.environ["SEAMLESS_API_KEY"],
)

reply = client.chat.completions.create(
    model="qwen/qwen2.5-0.5b-instruct",
    messages=[{"role": "user", "content": "Halo! Apa itu AI gateway?"}],
    max_tokens=500,
)
print(reply.choices[0].message.content)

max_tokens membatasi jawaban dan juga saldo yang ditahan selama request berjalan (lihat saldo).

Streaming

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.seamless.ai.id/v1",
    api_key=os.environ["SEAMLESS_API_KEY"],
)

stream = client.chat.completions.create(
    model="qwen/qwen2.5-0.5b-instruct",
    messages=[{"role": "user", "content": "Ceritakan sejarah singkat Jakarta."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
print()

Responses API

POST /v1/responses menerima format Responses API OpenAI untuk setiap model chat, dengan harga, saldo yang ditahan, dan tagihan yang sama dengan chat completions. Server tidak menyimpan jawaban: kirim percakapan lengkap di input setiap kali. Yang didukung dan yang ditolak ada di ringkasan.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.seamless.ai.id/v1",
    api_key=os.environ["SEAMLESS_API_KEY"],
)

response = client.responses.create(
    model="qwen/qwen2.5-0.5b-instruct",
    instructions="Jawab singkat dalam bahasa Indonesia.",
    input="Halo! Apa itu AI gateway?",
    max_output_tokens=500,
    store=False,
)
print(response.output_text)

stream = client.responses.create(
    model="qwen/qwen2.5-0.5b-instruct",
    input="Ceritakan sejarah singkat Jakarta.",
    stream=True,
    store=False,
)
for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
print()

Input gambar

Saat ini tidak ada model di daftar harga yang menerima gambar; request bergambar ke model berbayar ditolak (400 unsupported_content).

Memilih provider

Opsi gateway dikirim lewat extra_body. Contoh ini mencoba provider tertentu lebih dulu; opsi lain (only, exclude, data_policy, max_price) ada di ringkasan.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.seamless.ai.id/v1",
    api_key=os.environ["SEAMLESS_API_KEY"],
)

reply = client.chat.completions.create(
    model="qwen/qwen2.5-0.5b-instruct",
    messages=[{"role": "user", "content": "Halo!"}],
    # Field milik gateway, dicabut sebelum request diteruskan ke provider.
    extra_body={"gateway": {"routing": {"order": ["default"]}}},
)
print(reply.choices[0].message.content)

Embeddings

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.seamless.ai.id/v1",
    api_key=os.environ["SEAMLESS_API_KEY"],
)

result = client.embeddings.create(
    model="sentence-transformers/all-minilm-l6-v2",
    input=["Ibu kota Indonesia", "Harga beras hari ini"],
)
print(len(result.data[0].embedding))

Batch API

Untuk pekerjaan besar yang tidak perlu dijawab seketika (ribuan permintaan chat atau embedding): kirim semuanya dalam satu file JSONL, gateway menjalankannya dalam 24 jam, lalu unduh hasilnya. Contoh ini memakai qwen/qwen2.5-0.5b-instruct. Saat batch dibuat, biaya terburuk seluruh barisnya langsung ditahan dari saldo (setiap baris seperti permintaan langsung dengan max_tokens-nya); setiap baris lalu ditagih pemakaiannya saja dan sisanya kembali ke saldo saat baris selesai, batch dibatalkan, atau kedaluwarsa. Isi max_tokens di setiap baris supaya yang ditahan tidak besar. Aturan lengkapnya di ringkasan.

import json
import time
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.seamless.ai.id/v1",
    api_key=os.environ["SEAMLESS_API_KEY"],
)

questions = ["Apa ibu kota Jawa Barat?", "Sebutkan tiga makanan khas Padang."]
with open("permintaan.jsonl", "w") as file:
    for number, question in enumerate(questions, start=1):
        line = {
            "custom_id": f"soal-{number}",
            "method": "POST",
            "url": "/v1/chat/completions",
            "body": {
                "model": "qwen/qwen2.5-0.5b-instruct",
                "messages": [{"role": "user", "content": question}],
                "max_tokens": 300,
            },
        }
        file.write(json.dumps(line) + "\n")

with open("permintaan.jsonl", "rb") as file:
    uploaded = client.files.create(file=file, purpose="batch")
batch = client.batches.create(
    input_file_id=uploaded.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
)
print(batch.id, batch.status)

while batch.status not in ("completed", "failed", "expired", "cancelled"):
    time.sleep(30)
    batch = client.batches.retrieve(batch.id)
print(batch.status, batch.request_counts)

if batch.output_file_id:
    for text in client.files.content(batch.output_file_id).text.splitlines():
        result = json.loads(text)
        answer = result["response"]["body"]["choices"][0]["message"]["content"]
        print(result["custom_id"], answer)

Jawaban batches.create memuat hold_micro_idr, dana yang ditahan untuk batch itu (mikro-rupiah). Batch yang belum selesai dibatalkan dengan batches.cancel(id). Daftar batch, statusnya, dana yang ditahan, dan file hasilnya juga tampil di tab Batch di Playground dashboard.

Preset: ganti model tanpa deploy ulang

Simpan model, prompt sistem, parameter bawaan, dan batas jawaban sekali sebagai preset, lalu aplikasi cukup mengirim "model": "@preset/asisten-cs" ke /v1/chat/completions atau /v1/responses. Mengganti model atau prompt cukup di preset (panel Preset dashboard atau /v1/presets). Aturannya di ringkasan.

SDK tidak perlu diubah: nama preset dikirim sebagai model, dan reply.model menyebut model yang benar-benar melayani.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.seamless.ai.id/v1",
    api_key=os.environ["SEAMLESS_API_KEY"],
)

reply = client.chat.completions.create(
    model="@preset/asisten-cs",
    messages=[{"role": "user", "content": "Paket saya belum sampai, bagaimana?"}],
)
print(reply.model, reply.choices[0].message.content)

Kalau gagal

Error berformat OpenAI (error.type, error.code, error.param); daftar kode yang paling sering ada di ringkasan.