Gambar, video, musik, dan suara
Kunci yang Anda gunakan untuk teks juga membuat gambar, video, musik, dan suara, serta mengubah rekaman menjadi teks, dari saldo yang sama. Pilih model di tabel model (atau ?type=image, ?type=music, ?type=audio); halaman setiap model menunjukkan harga, jenis, dan contoh permintaan yang berfungsi.
| Anda ingin | Rute | Gambar sumber dimasukkan ke |
|---|---|---|
| Gambar baru dari prompt | POST /v1/images/generations |
(tidak ada) |
| Gambar yang diedit | POST /v1/images/edits |
image (atau image_url, input_images, images) |
| Video dari prompt | POST /v1/video/generations |
(tidak ada) |
| Video yang dimulai dari gambar | POST /v1/video/generations |
image_url (bingkai pertama); end_image_url untuk bingkai terakhir |
| Video dari gambar referensi | POST /v1/video/generations |
input_images dengan "role": "reference" |
| Jawaban teks tentang gambar | POST /v1/chat/completions |
bagian image_url di messages[].content |
| Musik | POST /v1/music/generations |
(tidak ada) |
| Suara dari teks | POST /v1/audio/speech |
(tidak ada) |
| Teks dari rekaman | POST /v1/audio/transcriptions |
(tidak ada; rekaman dimasukkan ke file) |
Gambar sumber adalah tautan https://, URI data: (data:image/png;base64,iVBORw0…) atau base64 biasa dari PNG, JPEG, atau WebP, hingga 8 per permintaan. Rute gambar juga menerima unggahan multipart (di bawah). Tautan harus berupa tautan https:// publik; tautan http:// ditolak. Tautan yang mengalihkan (misalnya https://picsum.photos/640/360) akan diikuti, hingga 5 kali dan hanya ke tautan https:// publik lainnya, dan model akan mendapatkan tautan tujuan akhirnya. Tautan yang tidak mengarah ke gambar, atau mengalihkan ke tempat yang tidak dapat kami gunakan, akan ditolak dengan 400 invalid_image_url sebelum ada yang ditahan atau dikenakan biaya. Gambar yang dikirim secara inline membuat permintaan lebih besar: jaga agar ukurannya di bawah 10 MB, atau kirim tautan.
Dalam pesan obrolan (image_url di messages[].content), tautan (https:// atau http://) dibuka oleh MartLLM dan dikirim ke model sebagai URL data:, karena sebagian besar model visi hanya menerima itu. Setiap gambar dapat berukuran hingga 20 MB (40 MB per permintaan), dan pengalihan diikuti hingga 5 kali, hanya ke alamat publik. Model Gemini mendapatkan tautan apa adanya. Tautan yang tidak mengarah ke gambar akan ditolak dengan 400 invalid_image_url, dan tidak ada biaya yang dikenakan.
Buat gambar
Gambar akan muncul di jawaban.
curl https://api.martllm.com/v1/images/generations \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "venice/z-image-turbo", "prompt": "a red apple on a white table", "n": 1, "size": "1024x1024"}'
{ "created": 1792429247, "data": [{ "url": "https://api.martllm.com/v1/media/artifacts/<id>/0" }],
"usage": { "cost_usd": 0.0099, "max_cost_usd": 0.0109 } }
usage.cost_usd adalah biaya gambar (juga di header X-UberLLM-Cost-USD). Dalam jawaban langka di mana harga belum diketahui, biayanya adalah null. Anda membayar sesuai yang ditagihkan penyedia, tidak pernah lebih dari max_cost_usd, yaitu jumlah yang ditahan untuk itu.
response_format secara default adalah url, baik untuk /v1/images/generations maupun /v1/images/edits. Kirim "response_format": "b64_json" untuk mendapatkan gambar di dalam jawaban sebagai gantinya. Ketika model mengembalikan gambar itu sendiri, MartLLM menyimpannya sebagai file akun Anda selama 24 jam dan menjawab dengan tautannya (https://api.martllm.com/v1/files/file_…/content), yang juga berfungsi sebagai gambar sumber untuk pengeditan selanjutnya. Unduh URL dengan kunci yang sama:
curl -L -o image.png -H "Authorization: Bearer $UBERLLM_API_KEY" \
"https://api.martllm.com/v1/media/artifacts/<id>/0"
n adalah 1 hingga 10.
Edit Gambar
Gunakan model yang mengedit (ID-nya biasanya berakhiran -edit) dan kirim gambar sumber di image:
curl https://api.martllm.com/v1/images/edits \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "google/nano-banana-pro-edit", "prompt": "make the sky a sunset",
"image": "https://example.com/skyline.png"}'
Gambar yang sama dapat dimasukkan sebagai:
"image": "data:image/png;base64,iVBORw0…""image_url": "https://…""input_images": ["https://…", "https://…"]: yang pertama adalah gambar yang akan diedit, sisanya adalah referensi. Sebuah entri juga bisa berupa{"url": "…", "role": "reference"}."images": [{"image_url": "https://…"}], bentuk yang dikirim oleh OpenAI SDK
Base64 biasa juga berfungsi, dan "input_image" dibaca sebagai "image".
Atau unggah file, seperti dengan edit gambar OpenAI:
curl https://api.martllm.com/v1/images/edits \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-F model=google/nano-banana-pro-edit -F prompt="make the sky a sunset" \
-F [email protected]
Edit tanpa gambar sumber akan ditolak dengan 400 image_required. Masker (inpainting) tidak didukung.
Unggah gambar sekali
Unggah gambar ke /v1/files dan gunakan dalam permintaan sebanyak yang Anda inginkan
selama 24 jam, alih-alih mengirimkannya di setiap permintaan:
curl https://api.martllm.com/v1/files \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-F [email protected]
{ "id": "file_3f9c…", "object": "file", "bytes": 482113, "content_type": "image/png",
"filename": "skyline.png", "created_at": 1792540800, "expires_at": 1792627200,
"url": "https://api.martllm.com/v1/files/file_3f9c…/content" }
Kemudian masukkan ID-nya, atau url, di mana pun gambar sumber digunakan: "image": "file_3f9c…",
"image": {"file_id": "file_3f9c…"}, "image_url": "file_3f9c…", entri dari
input_images, atau bingkai awal video. Hanya akun Anda yang dapat menggunakan file-nya.
- PNG, JPEG, WebP, GIF, HEIC atau AVIF, masing-masing hingga 10 MB, maksimal 500 disimpan per akun pada satu waktu.
- Disimpan selama 24 jam, lalu dihapus.
GET /v1/files/{id}menjelaskan satu,GET /v1/files/{id}/contentmengunduhnya,DELETE /v1/files/{id}menghapusnya sekarang.
Buat video
Video membutuhkan waktu satu menit atau lebih, jadi ini adalah pekerjaan: mulai, periksa, unduh.
1. Mulai
curl https://api.martllm.com/v1/video/generations \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"model": "fal-ai/vidu/q3/text-to-video/turbo", "prompt": "a red ball bouncing on green grass",
"duration_seconds": 5, "models": ["fal-ai/kling-video/v3/standard/text-to-video"]}'
models bersifat opsional: model cadangan dicoba secara berurutan hanya jika yang pertama tidak memiliki penyedia gratis saat ini, sehingga momen sibuk tidak menggagalkan permintaan Anda (lihat Model cadangan). Video di atas membutuhkan waktu sekitar satu menit dan berharga sekitar $0.33.
Untuk memulai dari gambar, gunakan model image-to-video dan tambahkan image_url:
-d '{"model": "bytedance/seedance-2-0-image-to-video", "prompt": "slow push-in as the waves roll",
"image_url": "https://example.com/first-frame.png", "duration_seconds": 5}'
Model yang memadukan dua gambar juga membutuhkan end_image_url (bingkai terakhir).
Model image-to-video atau reference-to-video yang tidak dapat membuat video dari teks saja akan ditolak dengan 400 image_required jika permintaan tidak memiliki gambar, sebelum biaya apa pun dikenakan. Model reference-to-video mengambil gambar dalam input_images:
-d '{"model": "pixverse/pixverse-c1-reference-to-video", "prompt": "the cat walks across the room",
"input_images": [{"url": "https://example.com/cat.png", "role": "reference"}],
"aspect_ratio": "16:9", "duration_seconds": 5}'
Bidang lain, jika model menawarkannya: resolution (480p, 720p, 1080p…), aspect_ratio (16:9, 9:16, 1:1…) dan audio (true / false; model tanpa pengaturan suara tidak akan dikirimi ini dan akan membuat klip seperti biasa).
Model image-to-video yang skemanya tidak mencantumkan aspect_ratios (kebanyakan model image-to-video Kling, Veo, Wan, dan Seedance) membuat klip dalam bentuk gambar sumber Anda. Kirimkan gambar yang sudah memiliki bentuk yang Anda inginkan (potong ke 9:16 untuk klip vertikal) dan biarkan aspect_ratio kosong. Bentuk yang dikirim ke model semacam itu akan dijawab 400 invalid_request sebelum biaya apa pun dikenakan ("aspect_ratio": "auto" diterima dan berarti sama dengan membiarkannya kosong).
Model reference-to-video membutuhkan bentuk, jadi ketika Anda membiarkan aspect_ratio kosong, itu akan dikirim sebagai 16:9 (atau bentuk pertama model jika tidak membuat 16:9); skema model menunjukkan default tersebut. Pilihan setiap model dicantumkan oleh GET /v1/models/<model id> (lihat Opsi setiap model).
Setiap model hanya membuat panjang klip, resolusi, dan bentuk tertentu. Permintaan untuk yang tidak dibuatnya akan ditolak dengan pesan yang mencantumkan yang dibuatnya, sebelum biaya apa pun dikenakan.
HTTP 202:
{
"id": "6f1c…",
"object": "media.job",
"kind": "video",
"status": "queued",
"model": "fal-ai/vidu/q3/text-to-video/turbo",
"estimated_cost_usd": 0.32725,
"estimated_cost_usdc": "327250",
"max_cost_usd": 0.359975,
"max_cost_usdc": "359975",
"poll_url": "/v1/video/generations/6f1c…",
"cancel_url": "/v1/video/generations/6f1c…"
}
model adalah model yang mengambil pekerjaan (cadangan dari models ketika yang pertama tidak bisa). Biaya yang berakhir dengan _usdc adalah dalam sepersejuta dolar (327250 = $0.33).
estimated_cost_usd adalah harga yang diharapkan. Ini dimulai sebagai harga terdaftar dari apa yang Anda minta (angka validate dan POST /v1/quote menjawab sebagai cost_usd: harga model saat ini dikalikan detik pada resolusi yang diminta, gambar, atau unit lainnya). Ketika penjual yang mengambil pekerjaan berharap untuk mengenakan biaya lebih dari itu untuk permintaan Anda, estimated_cost_usd adalah angka penjual tersebut: biasanya dari balasan pertama ini, dan paling lambat pada GET selanjutnya dari pekerjaan yang masih berjalan (beberapa pekerjaan mendapatkan penjualnya beberapa detik setelah dimulai, dan pekerjaan yang dipindahkan ke penjual lain mengambil harga penjual tersebut). Ini hanya akan naik, tidak pernah melewati max_cost_usd. Pekerjaan ditagih sesuai dengan yang dikenakan oleh penyedia: biasanya perkiraan atau kurang, dan dalam kasus yang jarang lebih (klip yang dibuat dari gambar yang harganya hanya ditetapkan oleh penjual saat selesai).
max_cost_usd adalah apa yang ditahan dari saldo Anda untuk pekerjaan tersebut: angka yang sama saat berjalan dan setelah selesai, dan jumlah maksimum yang ditagihkan untuk pekerjaan tersebut. Tidak ada pekerjaan yang pernah ditagih di atasnya, bahkan ketika penjual yang memulainya kehilangannya dan yang lain mengambil alih: penjual yang akan berharga lebih dari max_cost_usd Anda tidak digunakan. Model video yang harganya per second ditagih per detik klip; yang dihargai per job berharga segitu per video.
2. Periksa setiap 5–10 detik:
curl -H "Authorization: Bearer $UBERLLM_API_KEY" \
https://api.martllm.com/v1/video/generations/<job id>
HTTP 202 saat pekerjaan berjalan, HTTP 200 setelah selesai:
{
"id": "6f1c…",
"status": "succeeded",
"results": [{ "artifact_index": 0, "url": "https://api.martllm.com/v1/media/artifacts/6f1c…/0",
"content_type": "video/mp4", "duration_seconds": 5 }],
"usage": { "cost_usdc": "40000", "cost_usd": 0.04 }
}
Model melaporkan biaya pasti pekerjaan sedikit setelah file siap, biasanya dalam 30 detik. Sampai saat itu, pekerjaan succeeded menunjukkan "usage": { "cost_usd": null, "cost_pending": true }; tanyakan lagi beberapa detik kemudian. Jika biaya belum muncul dalam 30 menit, pekerjaan ditagih dengan harga terdaftarnya (estimated_cost_usd) dan usage.cost_note menyatakan demikian.
3. Unduh
curl -L -o video.mp4 -H "Authorization: Bearer $UBERLLM_API_KEY" \
https://api.martllm.com/v1/media/artifacts/<job id>/0
Minta untuk menghentikan pekerjaan yang tidak lagi Anda butuhkan: DELETE /v1/video/generations/<job id>. Kami meminta penyedia untuk menghentikannya; pekerjaan yang sudah dibuat akan ditagih seperti biasa, dan yang dihentikan akan berakhir canceled dan tidak dikenakan biaya.
Model video Fal
Model-model yang ID-nya dimulai dengan fal-ai/ berjalan di Fal, di bawah harga Fal sendiri:
Anda membayar harga Fal dikurangi diskon dari penjual Fal termurah di
marketplace saat ini (diskon 15% untuk 30 Oktober 2026; diskon 25% kapan pun penjual tersebut
menjual). Harga ditentukan oleh apa yang Anda minta — detik × tarif untuk
resolusi, dan apakah klip memiliki suara — jadi biaya pekerjaan diketahui saat
dimulai dan estimated_cost_usd adalah persis apa yang ditagihkan. Pekerjaan yang gagal
tidak dikenakan biaya. Menghentikan pekerjaan adalah upaya terbaik: jika Fal sudah membuat klipnya,
itu akan ditagihkan.
curl https://api.martllm.com/v1/video/generations \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "fal-ai/wan/v2.7/text-to-video", "prompt": "a woman twirls at a garden party at night",
"duration_seconds": 15, "resolution": "720p", "aspect_ratio": "9:16"}'
Harga Fal sendiri per detik (milik Anda adalah ini dikurangi diskon langsung;
halaman setiap model, GET /v1/models dan POST /v1/quote menunjukkan harga persisnya sekarang):
| Model | Durasi (dtk) | Harga Fal per detik, mulai dari |
|---|---|---|
fal-ai/wan/v2.7/text-to-video, …/image-to-video |
2–15 | 720p $0.10 · 1080p $0.15 |
fal-ai/kling-video/v3/standard/text-to-video, …/image-to-video |
3–15 | $0.084 · dengan suara $0.126 |
fal-ai/kling-video/v3/pro/text-to-video, …/image-to-video |
3–15 | $0.112 · dengan suara $0.168 |
fal-ai/kling-video/o3/standard/text-to-video, …/image-to-video |
3–15 | $0.084 · dengan suara $0.112 |
fal-ai/kling-video/v2.6/pro/text-to-video, …/image-to-video |
5, 10 | $0.07 · dengan suara $0.14 |
fal-ai/veo3.1/fast, fal-ai/veo3.1/fast/image-to-video |
4, 6, 8 | 720p/1080p $0.10 · dengan suara $0.15 · 4k $0.30 |
fal-ai/veo3.1, fal-ai/veo3.1/image-to-video |
4, 6, 8 | 720p/1080p $0.20 · dengan suara $0.40 · 4k $0.40 |
fal-ai/veo3.1/lite |
4, 6, 8 | 720p $0.03 · dengan suara $0.05 · 1080p $0.05 |
fal-ai/ltx-2.3/text-to-video/fast, …/image-to-video/fast |
6, 8, 10 | 1080p $0.06 · 1440p $0.12 · 2160p $0.24 |
fal-ai/ltx-2.3/text-to-video |
6, 8, 10 | 1080p $0.08 |
fal-ai/minimax/hailuo-02/standard/text-to-video, …/image-to-video |
6, 10 | 768P $0.045 · 512P (gambar) $0.017 |
fal-ai/vidu/q3/text-to-video/turbo, …/image-to-video/turbo |
1–16 | 360p/540p $0.035 · 720p/1080p $0.077 |
fal-ai/vidu/q3/text-to-video, …/image-to-video |
1–16 | 360p/540p $0.07 · 720p/1080p $0.154 |
Setiap harga adalah harga Fal sendiri; diskon akan diterapkan saat pekerjaan dimulai. Jika
penjual termurah menolak pekerjaan, penjual yang lebih mahal akan mengerjakannya dan pekerjaan
akan ditagihkan dengan harga penjual tersebut, tidak pernah lebih dari estimated_cost_usd pada balasan.
Beberapa model biaya kami lebih rendah dari yang tertera pada diskon penjual. Setiap 6 jam kami
membandingkan apa yang marketplace tagihkan kepada kami untuk setiap model selama 7 hari
terakhir dengan harga Fal untuk pekerjaan yang sama. Model dengan setidaknya 20 pekerjaan dalam waktu
tersebut kemudian dihargai berdasarkan bagian riil tersebut ditambah 5%, jika itu lebih rendah. Halaman model,
/v1/models dan tagihan semuanya menggunakan harga yang sama. Jika angka tersebut lebih dari
3 hari, diskon penjual berlaku lagi.
Bidang-bidang ini milik kami: duration_seconds, resolution, aspect_ratio, audio
dan image_url (atau input_images). Ejaan Fal sendiri (duration,
generate_audio, start_image_url) juga berfungsi. Kling, Veo, dan Kling 2.6 menambahkan suara
kecuali Anda mengirim "audio": false.
Status job
status |
HTTP | Arti |
|---|---|---|
queued |
202 | Diterima, menunggu model untuk memulainya |
running |
202 | Sedang dibuat; progress berubah dari 0 ke 1 saat model melaporkannya |
succeeded |
200 | Selesai; unduh results[].url |
failed |
200 | Tidak dibuat. error.message menjelaskan alasannya; error.retryable memberi tahu apakah mencoba lagi bisa berhasil |
canceled |
200 | Dihentikan sebelum dibuat |
expired |
200 | Tidak selesai tepat waktu |
Hanya ada enam status ini. failed, canceled, dan expired tidak dikenakan biaya. DELETE
adalah permintaan untuk menghentikan, bukan jaminan: job yang tetap diselesaikan oleh provider
akan berstatus succeeded dan ditagih.
Saat sedang sibuk, job akan dicoba ulang untuk Anda. Ketika tidak ada provider yang senggang untuk membuat video Anda,
atau sedang terlalu sibuk saat ini, MartLLM akan memulai ulang job secara otomatis, hingga dua kali lagi
dalam waktu 10 menit. Job ID dan batas biaya maksimalnya tetap sama.
Job hanya akan memakan waktu sedikit lebih lama. Anda hanya akan melihat failed jika semua percobaan gagal, dan
job yang gagal tidak dikenakan biaya.
Menunggu. Kirim callback_url dan kami akan memberi tahu Anda saat job selesai (lihat
Callback), atau periksa URL poll setiap 5–10 detik. Sebagian besar video memerlukan waktu
1–5 menit; beberapa job yang panjang atau 4K membutuhkan waktu lebih lama. Anda tidak perlu terus memeriksa agar
tagihannya diselesaikan: job yang tidak dicek oleh siapa pun akan tetap diselesaikan dan ditagih (atau
dikembalikan dananya) oleh MartLLM, serta muncul di
Dashboard → API Keys → Penggunaan API.
Panggilan Balik
Tambahkan callback_url ke pekerjaan video atau musik: sebuah tautan https:// di host publik.
Ketika pekerjaan telah selesai sepenuhnya, MartLLM mengirimkan POST ke sana dengan JSON
yang dikembalikan oleh GET pada pekerjaan tersebut.
{ "model": "kling/kling-o3", "prompt": "a red ball bouncing", "duration_seconds": 5,
"callback_url": "https://your-app.example/uberllm/jobs" }
- Kapan. Sekali, ketika pekerjaan telah selesai dan tagihannya final:
succeededdenganusage.cost_usddiatur (tidak pernahcost_pending), ataufailed,canceledatauexpired(biaya 0). Ini tidak dikirim lagi ketika biaya tiba, karena hanya dikirim setelahnya. Denganoutput_upload_urljuga, panggilan balik datang setelah unggahan selesai, jadioutput_upload.statussudahdeliveredataufailed. - Header.
Content-Type: application/json,MartLLM-Event: job.succeeded(ataujob.failed,job.canceled,job.expired),UberLLM-Event-Id: <job id>:<status>danUberLLM-Signature: t=<unix seconds>,v1=<hex>. - Percobaan Ulang. Jawab dengan 2xx apa pun dalam 15 detik. Jawaban lain, atau tidak ada jawaban, akan dicoba lagi setelah 30 detik, 2 menit, 10 menit, 30 menit dan 2 jam, kemudian dihentikan. Anda masih dapat melakukan polling pekerjaan kapan saja.
- Pengulangan. Sebuah pesan dapat tiba lebih dari sekali (misalnya ketika jawaban Anda hilang). ID acara tetap sama, jadi abaikan yang sudah Anda tangani.
- Status. Pekerjaan menunjukkan bagaimana hasilnya:
"callback": { "status": "delivered", "attempts": 1, "http_status": 200, "delivered_at": 1792540990 }.statusadalahpending,deliveredataufailed(denganerrordalam kata-kata biasa). - Tautan harus
https://di host publik, tanpa nama pengguna atau kata sandi di dalamnya. Ini tidak pernah ditampilkan kembali dan dihapus setelah panggilan balik berakhir.webhook_urldibaca sebagai bidang yang sama. Gambar dan ucapan tidak menerimanya: mereka kembali dalam jawaban itu sendiri.
Periksa tanda tangan
Setiap pesan ditandatangani dengan rahasia webhook akun Anda. Temukan di Dashboard → API keys → Webhook signing secret; itu dibuat pertama kali Anda membukanya, dan Ganti rahasia menukarnya sekaligus.
v1 adalah hex HMAC-SHA256 dari <t>.<raw body>, dikunci dengan seluruh rahasia
(whsec_…). Hitung itu di atas byte mentah yang Anda terima (sebelum mengurai JSON),
bandingkan dalam waktu konstan, dan tolak t yang lebih dari 5 menit.
Node.js (Express):
import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.UBERLLM_WEBHOOK_SECRET; // whsec_…
app.post("/uberllm/jobs", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("UberLLM-Signature") || "";
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
const expected = crypto.createHmac("sha256", SECRET)
.update(`${parts.t}.`).update(req.body).digest("hex");
const ok = parts.v1 && parts.v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected)) &&
Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
if (!ok) return res.status(400).send("bad signature");
const job = JSON.parse(req.body);
// Drop a repeat: req.get("UberLLM-Event-Id") is the same each time.
console.log(job.id, job.status, job.usage?.cost_usd);
res.sendStatus(204);
});
Python (Flask):
import hashlib, hmac, os, time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["UBERLLM_WEBHOOK_SECRET"].encode() # whsec_…
@app.post("/uberllm/jobs")
def uberllm_job():
raw = request.get_data() # the raw bytes, before any JSON parsing
parts = dict(p.split("=", 1) for p in request.headers.get("UberLLM-Signature", "").split(",") if "=" in p)
expected = hmac.new(SECRET, parts.get("t", "").encode() + b"." + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(parts.get("v1", ""), expected) or abs(time.time() - int(parts.get("t", "0"))) > 300:
abort(400)
job = request.get_json()
# Drop a repeat: request.headers["UberLLM-Event-Id"] is the same each time.
print(job["id"], job["status"], job.get("usage", {}).get("cost_usd"))
return "", 204
Peringatan ke webhook
Email peringatan juga dapat dikirim ke webhook: atur tautan di bawah
Dashboard → Credits → For developers: also send alerts to a webhook,
atau PUT /api/v1/billing/alerts {"alerts_webhook_url": "https://…"} (null mematikannya).
Pesan-pesan ditandatangani, dicoba ulang, dan diidentifikasi dengan cara yang sama seperti panggilan balik.
Isinya adalah:
{ "id": "evt_…", "object": "event", "type": "balance.low", "created": 1792540990,
"data": { "balance_usd": 4.2, "threshold_usd": 5, "message": "Your balance is $4.20, below the $5.00 you set. Requests stop once it runs out.",
"add_credits_url": "https://martllm.com/dashboard/credits" } }
balance.low: saldo jatuh di bawah jumlah yang Anda tetapkan untuk email saldo rendah. Dikirim sekali setiap kali jatuh di bawah; tidak ada yang dikirim sampai Anda menetapkan jumlah.hold.not_released: uang yang disisihkan untuk pekerjaan masih ditahan lebih dari 15 menit setelah pekerjaan berakhir.data.jobsmencantumkannya (id,kind,model,ended_at,held_usd) dandata.held_usdadalah totalnya. Uang itu masih milik Anda dan tim kami telah diberitahu.
Berapa lama file disimpan
Unduh hasilnya segera setelah dibuat:
- File video dan musik disimpan selama sekitar 3 jam setelah pekerjaan selesai.
- Tautan gambar ke
/v1/media/artifacts/…disimpan selama sekitar 15 menit; tautan gambar ke/v1/files/…selama 24 jam. Minta"response_format": "b64_json"untuk mendapatkan gambar di dalam jawaban dan menyimpannya sendiri. - Gambar yang Anda unggah ke
/v1/filesdisimpan selama 24 jam.
Setelah itu, unduhan akan menjawab 404 artifact_expired.
Kirim hasil ke penyimpanan Anda sendiri
Tambahkan output_upload_url ke pekerjaan video atau musik: tautan https:// yang menerima HTTP PUT, seperti tautan unggah S3, R2 yang sudah ditandatangani atau Google Cloud Storage. Ketika pekerjaan berhasil, MartLLM mengunggah file ke sana dengan tipe kontennya. Untuk pekerjaan yang membuat beberapa file, kirim output_upload_urls, satu tautan per file secara berurutan (maksimal 4).
{ "model": "kling/kling-o3", "prompt": "a red ball bouncing", "duration_seconds": 5,
"output_upload_url": "https://my-bucket.s3.amazonaws.com/ball.mp4?X-Amz-Signature=…" }
Status pekerjaan kemudian memiliki output_upload:
"output_upload": { "status": "delivered", "attempts": 1, "delivered_at": 1792540990,
"files": [{ "artifact_index": 0, "http_status": 200, "bytes": 5242880 }] }
statusadalahpendingsampai unggahan selesai, kemudiandeliveredataufailed(denganerrordalam kata-kata biasa).- Unggahan yang gagal dicoba lagi setelah 30 detik, 2, 10 dan 30 menit, kemudian ditandai
failed; file masih dapat diunduh dariresults[].urlselama disimpan. Buat tautan berlaku setidaknya selama satu jam. - Tautan harus
https://di host publik, tanpa nama pengguna atau kata sandi di dalamnya. Tautan tidak pernah ditampilkan kembali, dan dihapus setelah unggahan selesai. - Gambar tidak menerimanya: gambar kembali dalam jawaban itu sendiri.
Musik
Tiga langkah yang sama di /v1/music/generations. curl -OJ menyimpan treknya dengan nama file yang kita kirimkan.
Ucapan
Teks masuk, file audio keluar sebagai jawaban.
curl https://api.martllm.com/v1/audio/speech \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "x-ai/tts-xai-v1", "input": "Hello from MartLLM."}' \
-o speech.mp3
Anda juga bisa mengirim voice, response_format (misalnya mp3 atau wav) dan speed.
Setiap model memiliki suaranya sendiri (GET /v1/models/{id} mencantumkannya). Dengan
best-price:speech atau fastest:speech Anda tidak tahu sebelumnya model mana yang digunakan,
jadi suara disesuaikan dengannya: suara yang dimiliki model dipertahankan, nama-nama OpenAI dipetakan ke
suara model yang cocok jika ada (alloy → af_alloy), dan suara lain apa pun, atau
tidak ada, akan mendapatkan suara pertama model. Saat Anda menyebutkan nama model, suara Anda dikirim apa adanya.
Ini ditagih per 1K karakter input yang dimulai. Jawabannya adalah file audio;
header X-UberLLM-Cost-USD menyatakan biayanya, dan X-Request-Id adalah ID permintaan
seperti yang tercantum di Aktivitas. "validate": true, max_cost, metadata, models dan
provider.max_price berfungsi seperti pada gambar (lihat Apa yang Anda bayar).
Ubah rekaman menjadi teks
Kirim rekaman sebagai formulir dengan file dan model:
curl https://api.martllm.com/v1/audio/transcriptions \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-F model=venice/whisper-large-v3 \
-F [email protected]
{ "text": "Hello from MartLLM.", "duration": 4.2,
"usage": { "type": "duration", "seconds": 5, "cost_usd": 0.00055, "max_cost_usd": 0.00726 } }
usage.cost_usd adalah biayanya (juga di header X-UberLLM-Cost-USD, satu-satunya
tempat untuk jawaban text, srt, dan vtt). Kolom kami sendiri juga ada di formulir, dan tidak pernah dikirim ke model: -F max_cost=0.10, -F "metadata[project]=podcast",
-F validate=true.
Anda juga bisa mengirim language, prompt, temperature, dan response_format:
response_format |
Anda dapat |
|---|---|
json (standar) |
{ "text": …, "duration": …, "usage": … } |
text |
kata-kata sebagai teks biasa |
srt |
file teks dengan pengaturan waktu (SubRip), siap untuk editor video atau iklan |
vtt |
teks yang sama seperti WebVTT |
verbose_json |
jawaban json ditambah segments (id, start, end, text, dalam detik) dan, pada model yang mengatur waktu kata-kata tunggal, words |
curl https://api.martllm.com/v1/audio/transcriptions \
-H "Authorization: Bearer $UBERLLM_API_KEY" \
-F model=venice/whisper-large-v3 -F response_format=srt -F [email protected] -o captions.srt
1
00:00:00,330 --> 00:00:03,150
This serum is the one thing I use every morning.
2
00:00:03,300 --> 00:00:06,420
It took two weeks to see a change, now I never skip it.
venice/whisper-large-v3 memberikan satu teks per kalimat;
elevenlabs/elevenlabs-scribe-v2 mengatur waktu setiap kata, dan teksnya dipotong
menjadi baris maksimal 42 karakter, dengan baris baru setelah setiap kalimat. Jika model
tidak mengirimkan pengaturan waktu untuk rekaman, srt, vtt, dan verbose_json menjawab
400 timestamps_unavailable dan tidak ada biaya yang dikenakan. Ini ditagih per menit
audio, apa pun formatnya. File bisa berukuran hingga 40 MB. Formatnya (mp3, wav, ogg, flac, m4a/mp4,
webm, aac) dibaca dari rekaman itu sendiri, bukan nama filenya, jadi unggahan
bernama tmp123.out berfungsi.
Dengan OpenAI SDK
from openai import OpenAI
client = OpenAI(base_url="https://api.martllm.com/v1", api_key="<your MartLLM key>")
speech = client.audio.speech.create(model="x-ai/tts-xai-v1", voice="eve", input="Hello from MartLLM.")
speech.write_to_file("speech.mp3")
with open("speech.mp3", "rb") as f:
text = client.audio.transcriptions.create(model="venice/whisper-large-v3", file=f)
print(text.text)
Apa yang Anda bayar
- Harga dari apa yang dibuat: yang ditagihkan penyedia, tanpa biaya MartLLM. Jawaban gambar atau transkripsi dan pekerjaan yang selesai mencantumkannya sebagai
usage.cost_usd(dolar AS); setiap jawaban yang membuat sesuatu juga mencantumkannya di header responsX-UberLLM-Cost-USD(untuk ucapan, header adalah satu-satunya tempat, karena jawabannya adalah file audio). Itu tampil di Dasbor → Aktivitas. Sisa dana yang ditahan dikembalikan. - Tidak ada biaya untuk pekerjaan yang
failed, berstatuscanceledatauexpired, atau untuk permintaan gambar, ucapan, atau transkripsi yang gagal. - Penjual termurah yang membuat persis apa yang Anda minta. Banyak model gambar dan video punya lebih dari satu penjual; setiap permintaan pergi ke yang termurah yang bisa membuatnya dengan pengaturan Anda, dan ke penjual lain jika yang itu tidak bisa menerimanya. Daftar model dan setiap halaman model menampilkan harga di penjual termurah saat ini.
- Pengaturan routing key Anda (Dasbor → API key) memilih di antara penjual ketika salah satu lebih cepat: Harga terendah selalu mengambil yang termurah, default juga mengambil yang termurah kecuali terus gagal atau lebih dari dua kali lebih lambat daripada yang tercepat, Seimbang mengambil yang termurah yang paling banyak 20% lebih lambat daripada yang tercepat, dan Tercepat mengambil yang paling cepat, hingga harga yang tercantum untuk model. Kutipan dan
estimated_cost_usdpekerjaan menampilkan harga penjual yang dipilih pengaturan Anda. Lihat Pengaturan routing key Anda. - Lihat saldo Anda dan apa yang ditahan dengan
GET /v1/balance(di bawah).
Cek harga sebelum Anda membelanjakan
Tambahkan "validate": true ke permintaan gambar, video, musik, atau ucapan apa pun (untuk transkripsi, kirim validate=true sebagai kolom formulir bersama rekamannya). Permintaan diperiksa seolah-olah nyata (model, opsi, gambar sumber), tidak ada yang dibuat dan tidak ada yang ditagih, dan HTTP 200 menyebutkan berapa biayanya pada harga yang tercantum (cost_usd, harga yang ditampilkan di halaman model; Anda membayar apa yang ditagihkan penyedia, yang bisa berbeda) dan apa yang ditahan selama permintaan berjalan (max_cost_usd, jumlah maksimum yang ditagih):
{ "object": "quote", "model": "bytedance/seedance-2-0-image-to-video", "kind": "video",
"valid": true, "cost_usd": 0.2117, "max_cost_usd": 0.4235, "unit": "second", "units": 5, "duration_seconds": 5,
"note": "Nothing was charged. …" }
Jika penjual model memerlukan pengaturan yang Anda lewatkan (model reference-to-video memerlukan aspect_ratio), default yang dikirimkan bersamanya ditampilkan di schema model dan di kutipan sebagai defaults_applied, mis. "defaults_applied": {"aspect_ratio": "16:9"}.
Permintaan yang akan ditolak ditolak dengan cara yang sama, beserta alasannya.
Kunci harga selama 15 menit
POST /v1/quote menerima body yang sama dengan permintaan gambar, video, musik, atau ucapan dan menjawab dengan biaya yang tercantum (cost_usd), apa yang ditahan selama permintaan berjalan (max_cost_usd, jumlah maksimum yang ditagih) dan quote_id (untuk transkripsi, kirim model dan duration_seconds; transkripsi itu sendiri tidak menerima quote_id, gunakan max_cost untuk membatasinya):
curl https://api.martllm.com/v1/quote \
-H "Authorization: Bearer $UBERLLM_API_KEY" -H "Content-Type: application/json" \
-d '{"model": "kling/kling-o3", "prompt": "a red ball bouncing", "duration_seconds": 5}'
{ "object": "quote", "id": "6f1c…", "quote_id": "6f1c…", "model": "kling/kling-o3",
"kind": "video", "cost_usd": 0.225, "max_cost_usd": 0.495, "unit": "job", "units": 1,
"expires_at": 1792541700, "note": "Nothing was charged. …" }
Kirim permintaan yang sama dengan "quote_id": "6f1c…" dalam 15 menit dan akan ditagih sesuai yang ditagihkan penyedia, paling banyak max_cost_usd; jika yang harus ditahan saat mulai melebihi max_cost_usd, permintaan dibatalkan tanpa biaya. Tidak ada yang ditagih atau ditahan untuk kutipan itu sendiri.
- Satu kutipan memulai satu permintaan. Menggunakannya lagi menjawab
409 quote_used; pekerjaan yang tidak pernah mencapai model mengembalikan kutipannya. - Permintaan harus meminta hal yang sama: model yang sama dan pengaturan yang sama (prompt, ukuran, durasi klip, gambar sumber …). Apa pun selain itu ditolak dengan
400 quote_mismatch.max_cost,metadata, danoutput_upload_urlboleh berbeda. - Setelah 15 menit, kutipan menjawab
400 quote_expired. Model chat ditagih per token dan tidak punya kutipan: batasi denganprovider.max_price.
Model fallback dan batas harga
"models": ["model-b", "model-c"] menyebutkan model untuk dicoba secara berurutan ketika model pertama tidak dapat dilayani saat ini (no_available_provider) atau melebihi provider.max_price Anda. Penolakan lain apa pun langsung dijawab. model jawaban menyebutkan model yang membuatnya (jawaban ucapan adalah file audionya sendiri: Aktivitas menampilkan modelnya). Permintaan dengan quote_id tidak menerima models, dan transkripsi tidak menerima keduanya.
"provider": {"max_price": 0.05} adalah biaya maksimum per unit (satuan harga model unit: gambar, detik, megapiksel, menit, 1K karakter, atau permintaan), dalam dolar AS. Model di atasnya ditolak dengan 400 max_price_exceeded, dan permintaan tidak pernah ditagih di atas max_price kali unitnya. Opsi provider lainnya ditolak dengan 400 unsupported_routing_option, karena pilihan penjual untuk permintaan media tidak bisa diarahkan per permintaan.
"model": "best-price:image" (atau image-edit, text-to-video, image-to-video, music, speech, transcription) memilih model aktif termurah untuk pekerjaan itu; fastest: memilih yang tercepat berdasarkan pengukuran. Lihat Alias model.
Tag
"metadata": {"project": "spring-ads"} (hingga 16 nilai teks) disimpan bersama pekerjaan, dikembalikan pada statusnya, ditampilkan di Aktivitas dan di ekspor CSV, dan tidak pernah dikirim ke model. Pada transkripsi, kirim sebagai kolom formulir: -F "metadata[project]=spring-ads". Lihat Tag.
Tetapkan batas maksimum
Kirim "max_cost" (dolar AS, mis. 0.50) dengan permintaan gambar, video, musik, atau ucapan apa pun (kolom formulir pada transkripsi). Jika biayanya bisa lebih dari itu, permintaan ditolak dengan 400 max_cost_too_low dan tidak ada yang ditagih. Untuk pekerjaan video atau musik, batas maksimum yang tepat ditetapkan saat pekerjaan dimulai; jika kemudian hasilnya melebihi max_cost Anda, pekerjaan dibatalkan tanpa biaya. Dengan "validate": true, kutipan menambahkan within_max_cost.
Coba lagi tanpa membayar dua kali
Kirim header Idempotency-Key (string unik apa pun hingga 255 karakter, seperti UUID) saat Anda memulai pekerjaan video atau musik. Jika koneksi Anda terputus dan Anda mengirim permintaan yang sama lagi dengan key yang sama dalam 24 jam, Anda mendapatkan pekerjaan yang sama kembali, bukan pekerjaan kedua. Key yang sama dengan permintaan berbeda ditolak dengan 409 idempotency_key_reused. Permintaan gambar, ucapan, dan transkripsi tidak menerima key: permintaan yang gagal tidak ditagih, jadi kirimkan lagi.
Saldo Anda
curl -H "Authorization: Bearer $UBERLLM_API_KEY" https://api.martllm.com/v1/balance
{ "balance_usd": 12.40, "held_usd": 0.35, "available_usd": 12.05 }
held_usd disisihkan untuk permintaan yang masih berjalan; akan kembali (dikurangi biaya sebenarnya) setelah selesai. available_usd adalah yang dapat digunakan permintaan baru.
Opsi untuk setiap model
GET /v1/models?type=image (atau video, music, speech, transcription, audio untuk keduanya, chat, all; beberapa digabung dengan koma; tanpa type, daftar hanya berisi model chat) mencantumkan model yang bisa Anda panggil saat ini, masing-masing dengan type, endpoints untuk mengirimnya, dan pricing. GET /v1/models/<model id> memberikan satu model, dan untuk model media sebuah objek parameters: JSON Schema dari body request dengan panjang klip, resolusi, rasio aspek, dan ukuran yang didukungnya, serta gambar sumber yang dibutuhkannya.
curl -H "Authorization: Bearer $UBERLLM_API_KEY" \
https://api.martllm.com/v1/models/pixverse/pixverse-c1-reference-to-video
pricing memiliki usd (biaya paling mahal untuk satu unit saat ini) dan list_usd (harga dari pembuat model); model chat memiliki input_usd, output_usd, dan harga list_ mereka per 1M tokens.
usd adalah harga yang dikutip saat ini untuk request biasa ke model: penjual yang akan dituju request Anda dengan key yang diatur ke Balanced (default), sudah termasuk biaya kami. Daftar dan kutipan dihitung oleh kode yang sama dan mengikuti penjual kami dalam waktu sekitar 30 detik (penjual dijeda, dimatikan, atau diubah harganya).
Model yang harganya berdasarkan resolusi juga memiliki resolutions: satu baris per resolusi (resolusi video 480p / 720p / 1080p, resolusi gambar 1K / 2K / 4K), termurah lebih dulu, masing-masing dengan usd (harga yang dikutip untuk satu detik, atau satu gambar, pada resolusi itu) dan list_usd. usd di atas adalah baris termurah. Klip ditagih dengan harga resolusi yang diminta, dikali detiknya:
"pricing": {"usd": 0.100884, "unit": "second", "resolutions": [
{"resolution": "480p", "usd": 0.100884, "list_usd": 0.1287},
{"resolution": "720p", "usd": 0.2268, "list_usd": 0.289},
{"resolution": "1080p", "usd": 0.56133, "list_usd": 0.7107}]}
Sebagian penjual menetapkan harga untuk satu klip utuh, bukan per detik. Baris seperti itu juga memiliki seconds: panjang klip yang harga per detiknya adalah usd. Itu adalah tarif paling mahal (klip terpendek model), jadi klip yang lebih panjang biayanya kurang dari usd kali detiknya, dan request yang tidak menyebutkan panjang akan dikutip tepat usd kali seconds. seconds juga muncul saat suatu resolusi hanya dijual pada satu panjang.
{"resolution": "720p", "usd": 0.062344, "list_usd": 0.075, "seconds": 4}
Harga per detik dibulatkan ke $0.000001 terdekat. Untuk harga persis sebuah request, minta kutipan ("validate": true).
Kesalahan
| HTTP | kode | arti |
|---|---|---|
| 400 | wrong_endpoint |
misalnya model gambar dikirim ke /v1/video/generations, model chat dikirim ke rute gambar, atau model ucapan dikirim ke /v1/audio/transcriptions; pesan tersebut menyebutkan jalur yang benar. Tidak ada biaya yang dikenakan, dan Aktivitas mencantumkannya sebagai ditolak |
| 400 | invalid_request |
permintaan salah (pesan tersebut menjelaskan alasannya, misalnya durasi yang tidak ditawarkan model atau gambar sumber yang hilang) |
| 400 | image_required |
edit, atau model gambar-ke-video atau referensi-ke-video, tanpa gambar sumber |
| 400 | max_cost_too_low |
biayanya bisa lebih dari max_cost Anda; tidak ada biaya yang dikenakan |
| 400 | timestamps_unavailable |
srt, vtt atau verbose_json diminta dari model transkripsi yang tidak mengirimkan waktu; tidak ada biaya yang dikenakan |
| 409 | idempotency_key_reused |
Idempotency-Key itu digunakan untuk permintaan yang berbeda |
| 400 | quote_mismatch / quote_expired |
permintaan bukan yang dikutip, atau kutipan sudah lebih dari 15 menit |
| 404 | quote_not_found |
tidak ada kutipan seperti itu di akun Anda |
| 409 | quote_used |
kutipan itu sudah memulai permintaan |
| 400 | max_price_exceeded |
biaya model per unit lebih mahal dari provider.max_price Anda |
| 400 | unsupported_routing_option |
opsi provider selain max_price |
| 404 | file_not_found |
tidak ada file terunggah seperti itu di akun Anda, atau sudah kedaluwarsa |
| 413 | file_too_large |
unggah lebih dari 10 MB |
| 429 | too_many_files |
500 unggahan sudah disimpan; hapus beberapa atau tunggu sampai kedaluwarsa |
| 503 | files_unavailable |
unggah tidak tersedia saat ini |
| 413 | request_too_large |
permintaan melebihi batas ukuran (40 MB); kirim gambar sebagai tautan https:// dan bagi rekaman panjang |
| 402 | insufficient_credits |
saldo Anda tidak dapat menutupi biaya maksimum pekerjaan; pesan tersebut menyebutkan berapa yang dibutuhkan |
| 404 | model_not_found / not_found |
tidak ada model seperti itu, atau tidak ada pekerjaan seperti itu di akun Anda |
| 404 | artifact_expired |
file tidak lagi disimpan (lihat di atas) |
| 429 | rate_limited |
tunggu beberapa detik di Retry-After (beberapa detik jika tidak ada), lalu coba lagi; X-RateLimit-Remaining menunjukkan berapa banyak permintaan yang tersisa menit ini |
| 503 | no_available_provider |
tidak ada penjual yang bisa membuatnya saat ini; MartLLM sudah mencoba yang lain. Pesan tersebut menyebutkan model sejenis yang berfungsi sekarang |