NewHow we catch a seller listing the wrong model, and refund you if one does.

Images, video, music and speech

The key you use for text also makes images, videos, music and speech, and turns recordings into text, from the same balance. Pick a model in the models table (or ?type=image, ?type=music, ?type=audio); each model's page shows its price, its type and a working request.

You want Route Source picture goes in
A new image from a prompt POST /v1/images/generations (none)
An edited picture POST /v1/images/edits image (or image_url, input_images, images)
A video from a prompt POST /v1/video/generations (none)
A video that starts from a picture POST /v1/video/generations image_url (first frame); end_image_url for the last frame
A video from reference pictures POST /v1/video/generations input_images with "role": "reference"
A text answer about a picture POST /v1/chat/completions an image_url part in messages[].content
Music POST /v1/music/generations (none)
Speech from text POST /v1/audio/speech (none)
Text from a recording POST /v1/audio/transcriptions (none; the recording goes in file)

A source picture is an https:// link, a data: URI (data:image/png;base64,iVBORw0…) or plain base64 of a PNG, JPEG or WebP, up to 8 per request. The image routes also take a multipart upload (below). Links must be public https:// links; http:// links are refused. A link that redirects (for example https://picsum.photos/640/360) is followed, up to 5 times and only to other public https:// links, and the model gets the link it lands on. A link that does not lead to a picture, or redirects somewhere we cannot use, is refused with 400 invalid_image_url before anything is held or charged. Pictures sent inline make the request bigger: keep it under 10 MB, or send links.

In a chat message (image_url in messages[].content), a link (https:// or http://) is opened by MartLLM and sent to the model as a data: URL, because most vision models take only that. Each picture can be up to 20 MB (40 MB per request), and redirects are followed up to 5 times, only to public addresses. Gemini models get the link as it is. A link that does not lead to a picture is refused with 400 invalid_image_url, and nothing is charged.

Make an image

Images come back in the answer.

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 is what the picture cost (also in the X-UberLLM-Cost-USD header). In the rare answer where the price is not known yet it is null. You pay what the provider charged, never more than max_cost_usd, what was held for it.

response_format is url by default, for /v1/images/generations and /v1/images/edits alike. Send "response_format": "b64_json" to get the picture inside the answer instead. When the model hands back the picture itself, MartLLM keeps it as a file of your account for 24 hours and answers with its link (https://api.martllm.com/v1/files/file_…/content), which also works as the source picture of a later edit. Download a url with the same key:

curl -L -o image.png -H "Authorization: Bearer $UBERLLM_API_KEY" \
  "https://api.martllm.com/v1/media/artifacts/<id>/0"

n is 1 to 10.

Edit a picture

Use a model that edits (its id usually ends in -edit) and send the source picture in 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"}'

The same picture can go in as:

  • "image": "data:image/png;base64,iVBORw0…"
  • "image_url": "https://…"
  • "input_images": ["https://…", "https://…"]: the first is the picture to edit, the rest are references. An entry can also be {"url": "…", "role": "reference"}.
  • "images": [{"image_url": "https://…"}], the shape the OpenAI SDKs send

Plain base64 works too, and "input_image" is read as "image".

Or upload the file, as with OpenAI's image edit:

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]

An edit with no source picture is refused with 400 image_required. Masks (inpainting) are not supported.

Upload a picture once

Upload a picture to /v1/files and use it in as many requests as you like for 24 hours, instead of sending it in every request:

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" }

Then put the id, or the url, anywhere a source picture goes: "image": "file_3f9c…", "image": {"file_id": "file_3f9c…"}, "image_url": "file_3f9c…", an entry of input_images, or a video's start frame. Only your account can use its files.

  • PNG, JPEG, WebP, GIF, HEIC or AVIF, up to 10 MB each, at most 500 kept per account at a time.
  • Kept for 24 hours, then deleted. GET /v1/files/{id} describes one, GET /v1/files/{id}/content downloads it, DELETE /v1/files/{id} deletes it now.

Make a video

A video takes a minute or more, so it is a job: start it, check on it, download it.

1. Start it

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 is optional: backup models tried in order only when the first one has no free provider right now, so a busy moment does not fail your request (see Fallback models). The video above takes about a minute and costs about $0.33.

To start from a picture, use an image-to-video model and add 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}'

A model that blends two pictures also takes end_image_url (the last frame). An image-to-video or reference-to-video model that cannot make video from text alone is refused with 400 image_required when the request has no picture, before anything is charged. A reference-to-video model takes the pictures in 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}'

Other fields, where the model offers them: resolution (480p, 720p, 1080p…), aspect_ratio (16:9, 9:16, 1:1…) and audio (true / false; a model with no sound setting is not sent it and makes the clip as it always does).

An image-to-video model whose schema lists no aspect_ratios (most Kling, Veo, Wan and Seedance image-to-video models) makes the clip in the shape of your source picture. Send it a picture that already has the shape you want (crop to 9:16 for a vertical clip) and leave aspect_ratio out. A shape sent to such a model is answered 400 invalid_request before anything is charged ("aspect_ratio": "auto" is accepted and means the same as leaving it out).

A reference-to-video model needs a shape, so when you leave aspect_ratio out it is sent as 16:9 (or the model's first shape if it does not make 16:9); the model's schema shows that default. Each model's choices are listed by GET /v1/models/<model id> (see Each model's options).

Each model makes only certain clip lengths, resolutions and shapes. A request for one it does not make is refused with a message that lists the ones it does, before anything is charged.

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 is the model that took the job (a backup from models when the first could not). Costs ending in _usdc are in millionths of a dollar (327250 = $0.33). estimated_cost_usd is the price to expect. It starts as the listed price of what you asked for (the number validate and POST /v1/quote answer as cost_usd: the model's price now times the seconds at the resolution asked, images or other units). When the seller that takes the job expects to charge more than that for exactly your request, estimated_cost_usd is that seller's figure instead: usually from this first reply on, and at the latest on a later GET of a job that is still running (some jobs get their seller a few seconds after they start, and a job moved to another seller takes that seller's price). It only ever rises, never past max_cost_usd. The job is billed what the provider charged for it: usually the estimate or less, and in rare cases more (a clip made from a picture whose price the seller only sets when it ends). max_cost_usd is what is held from your balance for the job: the same figure while it runs and after it ends, and the most the job is billed. No job is ever billed above it, also when the seller that started it loses it and another one takes over: a seller that would cost more than your max_cost_usd is not used. A video model whose price is per second is billed per second of the clip; one priced per job costs that per video.

2. Check on it every 5–10 seconds:

curl -H "Authorization: Bearer $UBERLLM_API_KEY" \
  https://api.martllm.com/v1/video/generations/<job id>

HTTP 202 while the job runs, HTTP 200 once it ends:

{
  "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 }
}

The model reports a job's exact charge a little after the file is ready, usually within 30 seconds. Until then a succeeded job shows "usage": { "cost_usd": null, "cost_pending": true }; ask again a few seconds later. If the charge has not come within 30 minutes, the job is billed at its listed price (estimated_cost_usd) and usage.cost_note says so.

3. Download it

curl -L -o video.mp4 -H "Authorization: Bearer $UBERLLM_API_KEY" \
  https://api.martllm.com/v1/media/artifacts/<job id>/0

Ask to stop a job you no longer need: DELETE /v1/video/generations/<job id>. We ask the provider to stop it; a job it had already made is billed as usual, and one it stops ends canceled and costs nothing.

Fal video models

The models whose id starts with fal-ai/ run on Fal, below Fal's own price: you pay Fal's price less the discount of the cheapest Fal seller on the marketplace right now (15% off on 2026-10-30; 25% off whenever that seller is selling). The price is fixed by what you ask for — seconds × the rate for the resolution, and whether the clip has sound — so the job's cost is known when it starts and estimated_cost_usd is exactly what it is billed. A failed job costs nothing. Stopping one is best effort: if Fal has already made the clip, it is billed.

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"}'

Fal's own price per second (yours is this less the live discount; each model's page, GET /v1/models and POST /v1/quote show the exact price now):

Model Lengths (s) Fal's price per second, from
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 · with sound $0.126
fal-ai/kling-video/v3/pro/text-to-video, …/image-to-video 3–15 $0.112 · with sound $0.168
fal-ai/kling-video/o3/standard/text-to-video, …/image-to-video 3–15 $0.084 · with sound $0.112
fal-ai/kling-video/v2.6/pro/text-to-video, …/image-to-video 5, 10 $0.07 · with sound $0.14
fal-ai/veo3.1/fast, fal-ai/veo3.1/fast/image-to-video 4, 6, 8 720p/1080p $0.10 · with sound $0.15 · 4k $0.30
fal-ai/veo3.1, fal-ai/veo3.1/image-to-video 4, 6, 8 720p/1080p $0.20 · with sound $0.40 · 4k $0.40
fal-ai/veo3.1/lite 4, 6, 8 720p $0.03 · with sound $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 (image) $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

Each price is Fal's own; the discount comes off it when the job starts. If the cheapest seller turns a job down, a dearer one makes it and the job is billed at that seller's price, never more than estimated_cost_usd on the reply.

Some models cost us less than the seller's discount says. Every 6 hours we compare what the marketplace charged us for each model over the last 7 days with Fal's price for the same jobs. A model with at least 20 jobs in that time is then priced at that real share plus 5%, when that is lower. The model page, /v1/models and the bill all use the same price. If that figure is more than 3 days old, the seller's discount applies again.

The fields are ours: duration_seconds, resolution, aspect_ratio, audio and image_url (or input_images). Fal's own spelling (duration, generate_audio, start_image_url) works too. Kling, Veo and Kling 2.6 add sound unless you send "audio": false.

Job status

status HTTP Means
queued 202 Accepted, waiting for a model to start it
running 202 Being made; progress goes from 0 to 1 when the model reports it
succeeded 200 Done; download results[].url
failed 200 Not made. error.message says why; error.retryable says whether trying again can work
canceled 200 Stopped before it was made
expired 200 Not finished in time

These six are the only values. failed, canceled and expired cost nothing. A DELETE is a request to stop, not a promise: a job the provider finishes anyway ends succeeded and is billed.

A busy moment is retried for you. When no provider is free to make your video, or one is too busy right now, MartLLM starts the job again by itself, up to two more times within 10 minutes. It keeps the same job id and the same most-it-can-cost. The job just takes a little longer. You see failed only when every try failed, and a failed job costs nothing.

Waiting. Send callback_url and we tell you when the job ends (see Callbacks), or ask the poll URL every 5–10 seconds. Most videos take 1–5 minutes; some long or 4K jobs take longer. You don't have to keep asking for the bill to settle: a job nobody checks on is still finished and billed (or refunded) by MartLLM, and shows in Dashboard → API Keys → API Usage.

Callbacks

Add callback_url to a video or music job: an https:// link on a public host. When the job has ended for good, MartLLM sends a POST to it with the same JSON that GET on the job returns.

{ "model": "kling/kling-o3", "prompt": "a red ball bouncing", "duration_seconds": 5,
  "callback_url": "https://your-app.example/uberllm/jobs" }
  • When. Once, when the job has ended and its bill is final: succeeded with usage.cost_usd set (never cost_pending), or failed, canceled or expired (cost 0). It is not sent again when the cost arrives, because it is only sent after. With output_upload_url too, the callback comes after the upload is done, so output_upload.status is already delivered or failed.
  • Headers. Content-Type: application/json, MartLLM-Event: job.succeeded (or job.failed, job.canceled, job.expired), UberLLM-Event-Id: <job id>:<status> and UberLLM-Signature: t=<unix seconds>,v1=<hex>.
  • Retries. Answer with any 2xx within 15 seconds. Any other answer, or no answer, is tried again after 30 seconds, 2 minutes, 10 minutes, 30 minutes and 2 hours, then given up on. You can still poll the job at any time.
  • Repeats. A message can arrive more than once (for example when your answer is lost). The event id stays the same, so drop one you have already handled.
  • Status. The job shows how it went: "callback": { "status": "delivered", "attempts": 1, "http_status": 200, "delivered_at": 1792540990 }. status is pending, delivered or failed (with error in plain words).
  • The link must be https:// on a public host, with no user name or password in it. It is never shown back and is deleted once the callback ends. webhook_url is read as the same field. Images and speech do not take it: they come back in the answer itself.

Check the signature

Every message is signed with your account's webhook secret. Find it in Dashboard → API keys → Webhook signing secret; it is made the first time you open it, and Replace secret swaps it at once.

v1 is the hex HMAC-SHA256 of <t>.<raw body>, keyed with the whole secret (whsec_…). Compute it over the raw bytes you received (before parsing the JSON), compare in constant time, and refuse a t more than 5 minutes old.

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

Alerts to a webhook

The alert emails can also go to a webhook: set a link under Dashboard → Credits → For developers: also send alerts to a webhook, or PUT /api/v1/billing/alerts {"alerts_webhook_url": "https://…"} (null turns it off). The messages are signed, retried and identified the same way as callbacks. The body is:

{ "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: the balance fell below the amount you set for the low-balance email. Sent once each time it drops below; nothing is sent until you set an amount.
  • hold.not_released: money set aside for a job was still held more than 15 minutes after the job ended. data.jobs lists them (id, kind, model, ended_at, held_usd) and data.held_usd is the total. The money is still yours and our team has been told.

How long files are kept

Download a result soon after it is made:

  • Video and music files are kept for about 3 hours after the job ends.
  • Image links to /v1/media/artifacts/… are kept for about 15 minutes; image links to /v1/files/… for 24 hours. Ask for "response_format": "b64_json" to get the picture inside the answer and keep it yourself.
  • Pictures you upload to /v1/files are kept for 24 hours.

After that the download answers 404 artifact_expired.

Send results to your own storage

Add output_upload_url to a video or music job: an https:// link that accepts an HTTP PUT, such as a presigned S3, R2 or Google Cloud Storage upload link. When the job succeeds, MartLLM uploads the file there with its content type. For a job that makes several files, send output_upload_urls, one link per file in order (at most 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=…" }

The job's status then has output_upload:

"output_upload": { "status": "delivered", "attempts": 1, "delivered_at": 1792540990,
  "files": [{ "artifact_index": 0, "http_status": 200, "bytes": 5242880 }] }
  • status is pending until the upload is done, then delivered or failed (with error in plain words).
  • A failed upload is tried again after 30 seconds, 2, 10 and 30 minutes, then marked failed; the file can still be downloaded from results[].url while it is kept. Make the link valid for at least an hour.
  • The link must be https:// on a public host, with no user name or password in it. It is never shown back, and it is deleted once the upload ends.
  • Images do not take it: an image comes back in the answer itself.

Music

The same three steps at /v1/music/generations. curl -OJ saves the track under the file name we send.

Speech

Text goes in, an audio file comes back as the answer.

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

You can also send voice, response_format (for example mp3 or wav) and speed. Each model has its own voices (GET /v1/models/{id} lists them). With best-price:speech or fastest:speech you don't know in advance which model is used, so the voice is fitted to it: a voice the model has is kept, OpenAI's names map to the model's matching voice where it has one (alloy → af_alloy), and any other voice, or none, gets the model's first voice. When you name a model, your voice is sent as is. It is billed per started 1K characters of input. The answer is the audio file; its X-UberLLM-Cost-USD header says what it cost, and X-Request-Id is the request's id as listed in Activity. "validate": true, max_cost, metadata, models and provider.max_price work as on images (see What you pay).

Turn a recording into text

Send the recording as a form with file and 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 is what it cost (also in the X-UberLLM-Cost-USD header, the only place for text, srt and vtt answers). Our own fields go in the form too, and are never sent to the model: -F max_cost=0.10, -F "metadata[project]=podcast", -F validate=true.

You can also send language, prompt, temperature and response_format:

response_format You get
json (the default) { "text": …, "duration": …, "usage": … }
text the words as plain text
srt a caption file with timings (SubRip), ready for a video editor or an ad
vtt the same captions as WebVTT
verbose_json the json answer plus segments (id, start, end, text, in seconds) and, on a model that times single words, 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 gives one caption per sentence; elevenlabs/elevenlabs-scribe-v2 times every word, and its captions are cut into lines of at most 42 characters, a new one after each sentence. If a model sends no timings for a recording, srt, vtt and verbose_json answer 400 timestamps_unavailable and nothing is charged. It is billed per minute of audio, whatever the format. Files can be up to 40 MB. The format (mp3, wav, ogg, flac, m4a/mp4, webm, aac) is read from the recording itself, not its file name, so an upload named tmp123.out works.

With the 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)

What you pay

  • The price of what was made: what the provider charged, with no MartLLM fee. An image or transcription answer and a finished job carry it as usage.cost_usd (US dollars); every answer that made something also carries it in the X-UberLLM-Cost-USD response header (for speech, the header is the only place, since the answer is the audio file). It shows in Dashboard → Activity. The rest of the hold comes back.
  • Nothing for a job that failed, was canceled or expired, or for an image, speech or transcription request that fails.
  • The cheapest seller that makes exactly what you asked. Many image and video models have more than one seller; each request goes to the cheapest one that can make it with your settings, and to another if that one cannot take it. The model list and each model page show the price at the cheapest seller live now.
  • Your key's routing setting (Dashboard → API keys) chooses between sellers when one is faster: Lowest price always takes the cheapest, the default takes the cheapest too unless it keeps failing or is more than twice as slow as the fastest, Balanced takes the cheapest that is at most 20% slower than the fastest, and Fastest takes the quickest, up to the model's listed price. A quote and the job's estimated_cost_usd show the price of the seller your setting picks. See Your key's routing setting.
  • See your balance and what is held with GET /v1/balance (below).

Check the price before you spend

Add "validate": true to any image, video, music or speech request (for a transcription, send validate=true as a form field with the recording). The request is checked as if it were real (model, options, source pictures), nothing is made and nothing is charged, and HTTP 200 says what it costs at the listed price (cost_usd, the price shown on the model's page; you pay what the provider charged, which can differ) and what is held while it runs (max_cost_usd, the most it is billed):

{ "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. …" }

If the model's seller needs a setting you left out (a reference-to-video model needs aspect_ratio), the default it is sent with is shown on the model's schema and in the quote as defaults_applied, e.g. "defaults_applied": {"aspect_ratio": "16:9"}.

A request that would be refused is refused the same way, with the reason.

Hold a price for 15 minutes

POST /v1/quote takes the same body as the image, video, music or speech request and answers with the listed cost (cost_usd), what is held while it runs (max_cost_usd, the most it is billed) and a quote_id (for a transcription, send model and duration_seconds; a transcription itself takes no quote_id, use max_cost to cap it):

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. …" }

Send the same request with "quote_id": "6f1c…" within 15 minutes and it is billed what the provider charged, at most max_cost_usd; if what must be held when it starts is above max_cost_usd, it is cancelled at no charge. Nothing is charged or held for the quote itself.

  • One quote starts one request. Using it again answers 409 quote_used; a job that never reached a model gives the quote back.
  • The request must ask for the same thing: same model and the same settings (prompt, size, clip length, source pictures …). Anything else is refused with 400 quote_mismatch. max_cost, metadata and output_upload_url may differ.
  • After 15 minutes it answers 400 quote_expired. Chat models are billed per token and have no quote: cap them with provider.max_price.

Fallback models and a price cap

"models": ["model-b", "model-c"] names models to try in order when the first cannot be served right now (no_available_provider) or is above your provider.max_price. Any other refusal is answered at once. The answer's model names the model that made it (a speech answer is the audio file itself: Activity shows its model). A request with quote_id takes no models, and a transcription takes neither.

"provider": {"max_price": 0.05} is the most one unit (the model's pricing unit: image, second, megapixel, minute, 1K characters or request) may cost, in US dollars. A model above it is refused with 400 max_price_exceeded, and the request is never billed above max_price times its units. Other provider options are refused with 400 unsupported_routing_option, because seller choice for media requests cannot be steered per request.

"model": "best-price:image" (or image-edit, text-to-video, image-to-video, music, speech, transcription) picks the cheapest live model for the job; fastest: the quickest measured one. See Model aliases.

Tags

"metadata": {"project": "spring-ads"} (up to 16 text values) is stored with the job, returned on its status, shown in Activity and in the CSV export, and never sent to a model. On a transcription, send them as form fields: -F "metadata[project]=spring-ads". See Tags.

Set a ceiling

Send "max_cost" (US dollars, e.g. 0.50) with any image, video, music or speech request (a form field on a transcription). If it can cost more than that, it is refused with 400 max_cost_too_low and nothing is charged. For a video or music job the exact ceiling is set when the job starts; if it then comes out above your max_cost, the job is cancelled at no charge. With "validate": true, the quote adds within_max_cost.

Retry without paying twice

Send an Idempotency-Key header (any unique string up to 255 characters, such as a UUID) when you start a video or music job. If your connection drops and you send the same request again with the same key within 24 hours, you get the same job back instead of a second one. The same key with a different request is refused with 409 idempotency_key_reused. Image, speech and transcription requests do not take a key: one that failed was not charged, so send it again.

Your balance

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 is set aside for requests still running; it comes back (less the real cost) when they end. available_usd is what new requests can use.

Each model's options

GET /v1/models?type=image (or video, music, speech, transcription, audio for both of those, chat, all; several joined with commas; with no type the list is chat models only) lists the models you can call right now, each with its type, the endpoints to send it to and its pricing. GET /v1/models/<model id> gives one model, and for a media model a parameters object: a JSON Schema of the request body with the clip lengths, resolutions, aspect ratios and sizes it takes, and which source picture it needs.

curl -H "Authorization: Bearer $UBERLLM_API_KEY" \
  https://api.martllm.com/v1/models/pixverse/pixverse-c1-reference-to-video

pricing has usd (the most one unit costs now) and list_usd (the model maker's own price); a chat model has input_usd, output_usd and their list_ prices per 1M tokens.

usd is the price a plain request for the model is quoted right now: the seller your request would go to with a key set to Balanced (the default), our fee in. The lists and the quote are worked out by the same code and follow our sellers within about 30 seconds (a seller paused, switched off or repriced).

A model priced by resolution also has resolutions: one row per resolution (a video's 480p / 720p / 1080p, a picture's 1K / 2K / 4K), cheapest first, each with usd (what one second, or one picture, at that resolution is quoted) and list_usd. usd above is the cheapest row. A clip is billed at the price of the resolution it asks for, times its seconds:

"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}]}

Some sellers price a whole clip, not a second. Such a row also has seconds: the clip length its usd is the per-second price of. It is the dearest rate (the model's shortest clip), so a longer clip costs less than usd times its seconds, and a request that names no length is quoted exactly usd times seconds. seconds also appears where a resolution is sold at one length only.

{"resolution": "720p", "usd": 0.062344, "list_usd": 0.075, "seconds": 4}

A price per second is rounded to the nearest $0.000001. For the exact price of a request, ask for a quote ("validate": true).

Errors

HTTP code meaning
400 wrong_endpoint e.g. an image model sent to /v1/video/generations, a chat model sent to an image route, or a speech model sent to /v1/audio/transcriptions; the message names the right path. Nothing is charged, and Activity lists it as refused
400 invalid_request the request is wrong (the message says why, e.g. a duration the model doesn't offer or a missing source picture)
400 image_required an edit, or an image-to-video or reference-to-video model, with no source picture
400 max_cost_too_low it can cost more than your max_cost; nothing was charged
400 timestamps_unavailable srt, vtt or verbose_json asked of a transcription model that sent no timings; nothing was charged
409 idempotency_key_reused that Idempotency-Key was used for a different request
400 quote_mismatch / quote_expired the request is not the one quoted, or the quote is over 15 minutes old
404 quote_not_found no such quote on your account
409 quote_used that quote already started a request
400 max_price_exceeded the model costs more per unit than your provider.max_price
400 unsupported_routing_option a provider option other than max_price
404 file_not_found no such uploaded file on your account, or it expired
413 file_too_large an upload over 10 MB
429 too_many_files 500 uploads are already kept; delete some or wait for them to expire
503 files_unavailable uploads are not available right now
413 request_too_large the request is over the size limit (40 MB); send pictures as https:// links and split long recordings
402 insufficient_credits your balance can't cover the job's maximum cost; the message says how much it needs
404 model_not_found / not_found no such model, or no such job on your account
404 artifact_expired the file is no longer kept (see above)
429 rate_limited wait the seconds in Retry-After (a few seconds if it is absent), then retry; X-RateLimit-Remaining shows how many requests are left this minute
503 no_available_provider no seller can make it right now; MartLLM already tried the others. The message names the models of the same kind that work now