NovoComo detectamos um vendedor que oferece o modelo errado, e reembolsamos você se isso acontecer.
MartLLMantigo UberLLM

Imagens, vídeo, música e fala

A chave que você usa para texto também cria imagens, vídeos, música e fala, e transforma gravações em texto, a partir do mesmo saldo. Escolha um modelo na tabela de modelos (ou ?type=image, ?type=music, ?type=audio); a página de cada modelo mostra seu preço, seu tipo e uma requisição funcional.

Você quer Rota Imagem de origem vai em
Uma nova imagem a partir de um prompt POST /v1/images/generations (nenhum)
Uma imagem editada POST /v1/images/edits image (ou image_url, input_images, images)
Um vídeo a partir de um prompt POST /v1/video/generations (nenhum)
Um vídeo que começa a partir de uma imagem POST /v1/video/generations image_url (primeiro quadro); end_image_url para o último quadro
Um vídeo a partir de imagens de referência POST /v1/video/generations input_images com "role": "reference"
Uma resposta de texto sobre uma imagem POST /v1/chat/completions uma parte image_url em messages[].content
Música POST /v1/music/generations (nenhum)
Fala a partir de texto POST /v1/audio/speech (nenhum)
Texto a partir de uma gravação POST /v1/audio/transcriptions (nenhum; a gravação vai em file)

Uma imagem de origem é um link https://, uma URI data: (data:image/png;base64,iVBORw0…) ou base64 simples de um PNG, JPEG ou WebP, até 8 por requisição. As rotas de imagem também aceitam um upload multipart (abaixo). Links devem ser links https:// públicos; links http:// são recusados. Um link que redireciona (por exemplo https://picsum.photos/640/360) é seguido, até 5 vezes e apenas para outros links https:// públicos, e o modelo recebe o link para onde ele aponta. Um link que não leva a uma imagem, ou redireciona para algum lugar que não podemos usar, é recusado com 400 invalid_image_url antes que algo seja retido ou cobrado. Imagens enviadas inline tornam a requisição maior: mantenha-a abaixo de 10 MB, ou envie links.

Em uma mensagem de chat (image_url em messages[].content), um link (https:// ou http://) é aberto pelo MartLLM e enviado ao modelo como uma URL data:, porque a maioria dos modelos de visão aceita apenas isso. Cada imagem pode ter até 20 MB (40 MB por requisição), e os redirecionamentos são seguidos até 5 vezes, apenas para endereços públicos. Modelos Gemini recebem o link como ele é. Um link que não leva a uma imagem é recusado com 400 invalid_image_url, e nada é cobrado.

Criar uma imagem

Imagens são retornadas na resposta.

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 é o custo da imagem (também no cabeçalho X-UberLLM-Cost-USD). Na rara resposta onde o preço ainda não é conhecido, é null. Você paga o que o provedor cobrou, nunca mais do que max_cost_usd, o que foi reservado para isso.

response_format é url por padrão, tanto para /v1/images/generations quanto para /v1/images/edits. Envie "response_format": "b64_json" para obter a imagem dentro da resposta, em vez disso. Quando o modelo retorna a imagem em si, o MartLLM a mantém como um arquivo da sua conta por 24 horas e responde com seu link (https://api.martllm.com/v1/files/file_…/content), que também funciona como a imagem de origem para uma edição posterior. Baixe uma URL com a mesma chave:

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

n é 1 para 10.

Editar uma imagem

Use um modelo que edita (seu ID geralmente termina em -edit) e envie a imagem de origem em 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"}'

A mesma imagem pode ser enviada como:

  • "image": "data:image/png;base64,iVBORw0…"
  • "image_url": "https://…"
  • "input_images": ["https://…", "https://…"]: a primeira é a imagem a ser editada, o restante são referências. Uma entrada também pode ser {"url": "…", "role": "reference"}.
  • "images": [{"image_url": "https://…"}], o formato que os SDKs da OpenAI enviam

Base64 simples também funciona, e "input_image" é lido como "image".

Ou faça o upload do arquivo, como na edição de imagem da 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]

Uma edição sem imagem de origem é recusada com 400 image_required. Máscaras (inpainting) não são suportadas.

Faça upload de uma imagem uma vez

Faça upload de uma imagem para /v1/files e use-a em quantas requisições quiser por 24 horas, em vez de enviá-la em cada requisição:

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

Em seguida, coloque o id, ou o url, em qualquer lugar onde uma imagem de origem seja esperada: "image": "file_3f9c…", "image": {"file_id": "file_3f9c…"}, "image_url": "file_3f9c…", uma entrada de input_images, ou o frame inicial de um vídeo. Apenas sua conta pode usar seus arquivos.

  • PNG, JPEG, WebP, GIF, HEIC ou AVIF, até 10 MB cada, no máximo 500 mantidos por conta por vez.
  • Mantidos por 24 horas, depois excluídos. GET /v1/files/{id} descreve um, GET /v1/files/{id}/content o baixa, DELETE /v1/files/{id} o exclui agora.

Fazer um vídeo

Um vídeo leva um minuto ou mais, então é um trabalho: iniciá-lo, acompanhá-lo e baixá-lo.

1. Iniciá-lo

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 é opcional: modelos de backup tentados em ordem apenas quando o primeiro não tem um provedor disponível no momento, para que um momento de pico não faça sua solicitação falhar (veja Modelos de fallback). O vídeo acima leva cerca de um minuto e custa cerca de $0.33.

Para começar a partir de uma imagem, use um modelo de imagem para vídeo e adicione 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}'

Um modelo que mescla duas imagens também aceita end_image_url (o último quadro). Um modelo de imagem para vídeo ou de referência para vídeo que não consegue criar vídeo apenas a partir de texto é recusado com 400 image_required quando a solicitação não tem imagem, antes que qualquer coisa seja cobrada. Um modelo de referência para vídeo aceita as imagens em 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}'

Outros campos, onde o modelo os oferece: resolution (480p, 720p, 1080p…), aspect_ratio (16:9, 9:16, 1:1…) e audio (true / false; um modelo sem configuração de som não o recebe e cria o clipe como sempre faz).

Um modelo de imagem para vídeo cujo esquema não lista aspect_ratios (a maioria dos modelos de imagem para vídeo Kling, Veo, Wan e Seedance) cria o clipe no formato da sua imagem de origem. Envie uma imagem que já tenha o formato desejado (corte para 9:16 para um clipe vertical) e deixe aspect_ratio de fora. Um formato enviado a tal modelo é respondido com 400 invalid_request antes que qualquer coisa seja cobrada ("aspect_ratio": "auto" é aceito e significa o mesmo que deixá-lo de fora).

Um modelo de referência para vídeo precisa de um formato, então, quando você deixa aspect_ratio de fora, ele é enviado como 16:9 (ou o primeiro formato do modelo se ele não criar 16:9); o esquema do modelo mostra esse padrão. As opções de cada modelo são listadas por GET /v1/models/<model id> (veja Opções de cada modelo).

Cada modelo cria apenas certas durações de clipe, resoluções e formatos. Uma solicitação para um que ele não cria é recusada com uma mensagem que lista os que ele cria, antes que qualquer coisa seja cobrada.

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 é o modelo que aceitou o trabalho (um backup de models quando o primeiro não pôde). Custos terminados em _usdc estão em milionésimos de dólar (327250 = $0.33). estimated_cost_usd é o preço a ser esperado. Ele começa como o preço listado do que você solicitou (os números validate e POST /v1/quote respondem como cost_usd: o preço atual do modelo vezes os segundos na resolução solicitada, imagens ou outras unidades). Quando o vendedor que aceita o trabalho espera cobrar mais do que isso pela sua solicitação exata, estimated_cost_usd é o valor desse vendedor em vez disso: geralmente a partir desta primeira resposta, e o mais tardar em uma GET posterior de um trabalho que ainda está em execução (alguns trabalhos obtêm seu vendedor alguns segundos depois de começarem, e um trabalho movido para outro vendedor assume o preço desse vendedor). Ele só aumenta, nunca ultrapassando max_cost_usd. O trabalho é cobrado pelo que o provedor cobrou por ele: geralmente a estimativa ou menos, e em casos raros mais (um clipe feito a partir de uma imagem cujo preço o vendedor só define quando termina). max_cost_usd é o que é retido do seu saldo para o trabalho: o mesmo valor enquanto ele está em execução e depois que termina, e o máximo que o trabalho é cobrado. Nenhum trabalho é cobrado acima disso, mesmo quando o vendedor que o iniciou o perde e outro assume: um vendedor que custaria mais do que seu max_cost_usd não é usado. Um modelo de vídeo cujo preço é por second é cobrado por segundo do clipe; um precificado por job custa isso por vídeo.

2. Acompanhá-lo a cada 5–10 segundos:

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

HTTP 202 enquanto o trabalho está em execução, HTTP 200 assim que termina:

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

O modelo informa a cobrança exata de um trabalho um pouco depois que o arquivo está pronto, geralmente dentro de 30 segundos. Até então, um trabalho succeeded mostra "usage": { "cost_usd": null, "cost_pending": true }; pergunte novamente alguns segundos depois. Se a cobrança não tiver chegado dentro de 30 minutos, o trabalho é cobrado pelo seu preço listado (estimated_cost_usd) e usage.cost_note indica isso.

3. Baixá-lo

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

Peça para parar um trabalho que você não precisa mais: DELETE /v1/video/generations/<job id>. Pedimos ao provedor para pará-lo; um trabalho que ele já havia feito é cobrado normalmente, e um que ele para termina canceled e não custa nada.

Modelos de vídeo Fal

Os modelos cujo ID começa com fal-ai/ rodam no Fal, abaixo do preço próprio do Fal: você paga o preço do Fal menos o desconto do vendedor Fal mais barato no marketplace agora (15% de desconto em 30 de outubro de 2026; 25% de desconto sempre que esse vendedor estiver vendendo). O preço é fixado pelo que você pede — segundos × a taxa para a resolução, e se o clipe tem som — então o custo do trabalho é conhecido quando ele começa e estimated_cost_usd é exatamente o que é cobrado. Um trabalho falho não custa nada. Parar um é o melhor esforço: se o Fal já fez o clipe, ele é cobrado.

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

Preço próprio do Fal por segundo (o seu é este menos o desconto ao vivo; a página de cada modelo, GET /v1/models e POST /v1/quote mostram o preço exato agora):

Modelo Duração (s) Preço do Fal por segundo, a partir de
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 · com som $0.126
fal-ai/kling-video/v3/pro/text-to-video, …/image-to-video 3–15 $0.112 · com som $0.168
fal-ai/kling-video/o3/standard/text-to-video, …/image-to-video 3–15 $0.084 · com som $0.112
fal-ai/kling-video/v2.6/pro/text-to-video, …/image-to-video 5, 10 $0.07 · com som $0.14
fal-ai/veo3.1/fast, fal-ai/veo3.1/fast/image-to-video 4, 6, 8 720p/1080p $0.10 · com som $0.15 · 4k $0.30
fal-ai/veo3.1, fal-ai/veo3.1/image-to-video 4, 6, 8 720p/1080p $0.20 · com som $0.40 · 4k $0.40
fal-ai/veo3.1/lite 4, 6, 8 720p $0.03 · com som $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 (imagem) $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

Cada preço é próprio do Fal; o desconto é aplicado quando o trabalho começa. Se o vendedor mais barato recusar um trabalho, um mais caro o fará e o trabalho será cobrado pelo preço desse vendedor, nunca mais do que estimated_cost_usd na resposta.

Alguns modelos nos custam menos do que o desconto do vendedor indica. A cada 6 horas comparamos o que o marketplace nos cobrou por cada modelo nos últimos 7 dias com o preço do Fal para os mesmos trabalhos. Um modelo com pelo menos 20 trabalhos nesse período é então precificado com essa participação real mais 5%, quando isso for menor. A página do modelo, /v1/models e a fatura usam o mesmo preço. Se esse valor tiver mais de 3 dias, o desconto do vendedor se aplica novamente.

Os campos são nossos: duration_seconds, resolution, aspect_ratio, audio e image_url (ou input_images). A grafia própria do Fal (duration, generate_audio, start_image_url) também funciona. Kling, Veo e Kling 2.6 adicionam som a menos que você envie "audio": false.

Status do job

status HTTP Significado
queued 202 Aceito, aguardando um modelo iniciar
running 202 Sendo gerado; progress vai de 0 a 1 quando o modelo informa
succeeded 200 Concluído; baixe results[].url
failed 200 Não gerado. error.message diz o motivo; error.retryable diz se tentar novamente pode funcionar
canceled 200 Interrompido antes de ser gerado
expired 200 Não finalizado a tempo

Esses seis são os únicos valores. failed, canceled e expired não custam nada. Um DELETE é uma solicitação para interromper, não uma garantia: um job que o provedor terminar de qualquer forma termina como succeeded e é cobrado.

Tentamos novamente se o sistema estiver ocupado. Quando nenhum provedor estiver livre para gerar seu vídeo, ou se algum estiver ocupado demais no momento, a MartLLM reinicia o job por conta própria, até mais duas vezes em até 10 minutos. Ele mantém o mesmo job id e o mesmo custo máximo. O job só leva um pouco mais de tempo. Você só verá failed se todas as tentativas falharem, e um job que falha não custa nada.

Aguardando. Envie callback_url e avisamos você quando o job terminar (veja Callbacks), ou consulte a URL de polling a cada 5–10 segundos. A maioria dos vídeos leva de 1 a 5 minutos; alguns jobs longos ou de 4K demoram mais. Você não precisa ficar consultando para que a cobrança seja processada: um job que ninguém acompanha ainda assim é finalizado e cobrado (ou reembolsado) pela MartLLM, e aparece em Dashboard → API Keys → API Usage.

Callbacks

Adicione callback_url a um trabalho de vídeo ou música: um link https:// em um host público. Quando o trabalho tiver terminado de vez, o MartLLM envia um POST para ele com o mesmo JSON que GET no trabalho retorna.

{ "model": "kling/kling-o3", "prompt": "a red ball bouncing", "duration_seconds": 5,
  "callback_url": "https://your-app.example/uberllm/jobs" }
  • Quando. Uma vez, quando o trabalho tiver terminado e sua fatura for final: succeeded com usage.cost_usd definido (nunca cost_pending), ou failed, canceled ou expired (custo 0). Não é enviado novamente quando o custo chega, porque é enviado apenas depois. Com output_upload_url também, o callback chega depois que o upload é concluído, então output_upload.status já está delivered ou failed.
  • Cabeçalhos. Content-Type: application/json, MartLLM-Event: job.succeeded (ou job.failed, job.canceled, job.expired), UberLLM-Event-Id: <job id>:<status> e UberLLM-Signature: t=<unix seconds>,v1=<hex>.
  • Tentativas. Responda com qualquer 2xx dentro de 15 segundos. Qualquer outra resposta, ou nenhuma resposta, é tentada novamente após 30 segundos, 2 minutos, 10 minutos, 30 minutos e 2 horas, e então desistida. Você ainda pode consultar o trabalho a qualquer momento.
  • Repetições. Uma mensagem pode chegar mais de uma vez (por exemplo, quando sua resposta é perdida). O ID do evento permanece o mesmo, então descarte um que você já tenha processado.
  • Status. O trabalho mostra como foi: "callback": { "status": "delivered", "attempts": 1, "http_status": 200, "delivered_at": 1792540990 }. status é pending, delivered ou failed (com error em palavras simples).
  • O link deve ser https:// em um host público, sem nome de usuário ou senha nele. Ele nunca é exibido de volta e é excluído assim que o callback termina. webhook_url é lido como o mesmo campo. Imagens e fala não o utilizam: eles retornam na própria resposta.

Verifique a assinatura

Toda mensagem é assinada com o segredo de webhook da sua conta. Encontre-o em Dashboard → API keys → Webhook signing secret; ele é criado na primeira vez que você o abre, e Replace secret o troca imediatamente.

v1 é o HMAC-SHA256 hexadecimal de <t>.<raw body>, com chave de todo o segredo (whsec_…). Calcule-o sobre os bytes brutos que você recebeu (antes de analisar o JSON), compare em tempo constante e recuse um t com mais de 5 minutos.

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

Alertas para um webhook

Os e-mails de alerta também podem ir para um webhook: defina um link em Dashboard → Credits → For developers: also send alerts to a webhook, ou PUT /api/v1/billing/alerts {"alerts_webhook_url": "https://…"} (null o desativa). As mensagens são assinadas, retentadas e identificadas da mesma forma que os callbacks. O corpo é:

{ "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: o saldo caiu abaixo do valor que você definiu para o e-mail de saldo baixo. Enviado uma vez cada vez que cai abaixo; nada é enviado até que você defina um valor.
  • hold.not_released: dinheiro reservado para um trabalho ainda estava retido mais de 15 minutos após o término do trabalho. data.jobs os lista (id, kind, model, ended_at, held_usd) e data.held_usd é o total. O dinheiro ainda é seu e nossa equipe foi informada.

Por quanto tempo os arquivos são mantidos

Baixe um resultado logo depois que ele for gerado:

  • Arquivos de vídeo e música são mantidos por cerca de 3 horas após a conclusão da tarefa.
  • Links de imagem para /v1/media/artifacts/… são mantidos por cerca de 15 minutos; links de imagem para /v1/files/… por 24 horas. Peça por "response_format": "b64_json" para obter a imagem dentro da resposta e guardá-la você mesmo.
  • Imagens que você envia para /v1/files são mantidas por 24 horas.

Depois disso, o download responde 404 artifact_expired.

Envie resultados para seu próprio armazenamento

Adicione output_upload_url a uma tarefa de vídeo ou música: um link https:// que aceita um HTTP PUT, como um link de upload S3, R2 pré-assinado ou do Google Cloud Storage. Quando a tarefa é bem-sucedida, o MartLLM faz o upload do arquivo para lá com seu tipo de conteúdo. Para uma tarefa que gera vários arquivos, envie output_upload_urls, um link por arquivo em ordem (no máximo 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=…" }

O status da tarefa então tem output_upload:

"output_upload": { "status": "delivered", "attempts": 1, "delivered_at": 1792540990,
  "files": [{ "artifact_index": 0, "http_status": 200, "bytes": 5242880 }] }
  • status é pending até o upload ser concluído, então delivered ou failed (com error em palavras simples).
  • Um upload falho é tentado novamente após 30 segundos, 2, 10 e 30 minutos, então marcado failed; o arquivo ainda pode ser baixado de results[].url enquanto é mantido. Torne o link válido por pelo menos uma hora.
  • O link deve ser https:// em um host público, sem nome de usuário ou senha. Ele nunca é exibido de volta e é excluído assim que o upload termina.
  • Imagens não aceitam isso: uma imagem retorna na própria resposta.

Música

Os mesmos três passos em /v1/music/generations. curl -OJ salva a faixa com o nome de arquivo que enviamos.

Fala

O texto entra, um arquivo de áudio retorna como resposta.

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

Você também pode enviar voice, response_format (por exemplo mp3 ou wav) e speed. Cada modelo tem suas próprias vozes (GET /v1/models/{id} as lista). Com best-price:speech ou fastest:speech você não sabe antecipadamente qual modelo é usado, então a voz é ajustada a ele: uma voz que o modelo possui é mantida, os nomes da OpenAI são mapeados para a voz correspondente do modelo onde ele tiver uma (alloy → af_alloy), e qualquer outra voz, ou nenhuma, recebe a primeira voz do modelo. Quando você nomeia um modelo, sua voz é enviada como está. É cobrado por 1K caracteres iniciados de input. A resposta é o arquivo de áudio; seu cabeçalho X-UberLLM-Cost-USD informa o custo, e X-Request-Id é o ID da requisição conforme listado em Atividade. "validate": true, max_cost, metadata, models e provider.max_price funcionam como nas imagens (veja O que você paga).

Transformar uma gravação em texto

Envie a gravação como um formulário com file e 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 é o que custou (também no cabeçalho X-UberLLM-Cost-USD, o único lugar para as respostas text, srt e vtt). Nossos próprios campos também vão no formulário e nunca são enviados ao modelo: -F max_cost=0.10, -F "metadata[project]=podcast", -F validate=true.

Você também pode enviar language, prompt, temperature e response_format:

response_format Você recebe
json (o padrão) { "text": …, "duration": …, "usage": … }
text as palavras como texto simples
srt um arquivo de legendas com marcações de tempo (SubRip), pronto para um editor de vídeo ou um anúncio
vtt as mesmas legendas como WebVTT
verbose_json a resposta json mais segments (id, start, end, text, em segundos) e, em um modelo que marca o tempo de palavras individuais, 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 dá uma legenda por frase; elevenlabs/elevenlabs-scribe-v2 marca o tempo de cada palavra, e suas legendas são cortadas em linhas de no máximo 42 caracteres, uma nova após cada frase. Se um modelo não envia marcações de tempo para uma gravação, srt, vtt e verbose_json respondem 400 timestamps_unavailable e nada é cobrado. É cobrado por minuto de áudio, qualquer que seja o formato. Os arquivos podem ter até 40 MB. O formato (mp3, wav, ogg, flac, m4a/mp4, webm, aac) é lido da própria gravação, não do nome do arquivo, então um upload chamado tmp123.out funciona.

Com o 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)

O que você paga

  • O preço do que foi feito: o que o provedor cobrou, sem taxa MartLLM. Uma resposta de imagem ou transcrição e um trabalho concluído o incluem como usage.cost_usd (dólares americanos); toda resposta que fez algo também o inclui no cabeçalho de resposta X-UberLLM-Cost-USD (para fala, o cabeçalho é o único lugar, já que a resposta é o arquivo de áudio). Ele aparece em Painel → Atividade. O restante da retenção é devolvido.
  • Nada por um trabalho que failed, foi canceled ou expired, ou por uma solicitação de imagem, fala ou transcrição que falha.
  • O vendedor mais barato que faz exatamente o que você pediu. Muitos modelos de imagem e vídeo têm mais de um vendedor; cada solicitação vai para o mais barato que pode fazê-lo com suas configurações, e para outro se aquele não puder aceitá-la. A lista de modelos e cada página de modelo mostram o preço do vendedor mais barato ativo agora.
  • A configuração de roteamento da sua chave (Painel → Chaves de API) escolhe entre vendedores quando um é mais rápido: Preço mais baixo sempre pega o mais barato, o padrão também pega o mais barato a menos que continue falhando ou seja mais de duas vezes mais lento que o mais rápido, Balanceado pega o mais barato que é no máximo 20% mais lento que o mais rápido, e Mais rápido pega o mais rápido, até o preço listado do modelo. Uma cotação e o estimated_cost_usd do trabalho mostram o preço do vendedor que sua configuração escolhe. Veja Configuração de roteamento da sua chave.
  • Veja seu saldo e o que está retido com GET /v1/balance (abaixo).

Verifique o preço antes de gastar

Adicione "validate": true a qualquer solicitação de imagem, vídeo, música ou fala (para uma transcrição, envie validate=true como um campo de formulário com a gravação). A solicitação é verificada como se fosse real (modelo, opções, imagens de origem), nada é feito e nada é cobrado, e HTTP 200 informa o que custa ao preço listado (cost_usd, o preço mostrado na página do modelo; você paga o que o provedor cobrou, o que pode diferir) e o que é retido enquanto executa (max_cost_usd, o máximo que será cobrado):

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

Se o vendedor do modelo precisar de uma configuração que você omitiu (um modelo de referência para vídeo precisa de aspect_ratio), o padrão com o qual é enviado é mostrado no esquema do modelo e na cotação como defaults_applied, ex. "defaults_applied": {"aspect_ratio": "16:9"}.

Uma solicitação que seria recusada é recusada da mesma forma, com o motivo.

Manter um preço por 15 minutos

POST /v1/quote usa o mesmo corpo que a solicitação de imagem, vídeo, música ou fala e responde com o custo listado (cost_usd), o que é retido enquanto executa (max_cost_usd, o máximo que será cobrado) e um quote_id (para uma transcrição, envie model e duration_seconds; uma transcrição em si não usa quote_id, use max_cost para limitá-la):

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

Envie a mesma solicitação com "quote_id": "6f1c…" dentro de 15 minutos e será cobrado o que o provedor cobrou, no máximo max_cost_usd; se o que deve ser retido quando começa estiver acima de max_cost_usd, é cancelado sem custo. Nada é cobrado ou retido pela cotação em si.

  • Uma cotação inicia uma solicitação. Usá-la novamente responde 409 quote_used; um trabalho que nunca alcançou um modelo devolve a cotação.
  • A solicitação deve pedir a mesma coisa: mesmo modelo e as mesmas configurações (prompt, tamanho, duração do clipe, imagens de origem…). Qualquer outra coisa é recusada com 400 quote_mismatch. max_cost, metadata e output_upload_url podem diferir.
  • Após 15 minutos, responde 400 quote_expired. Modelos de chat são cobrados por token e não têm cotação: limite-os com provider.max_price.

Modelos de fallback e um limite de preço

"models": ["model-b", "model-c"] nomeia modelos para tentar em ordem quando o primeiro não pode ser atendido agora (no_available_provider) ou está acima do seu provider.max_price. Qualquer outra recusa é respondida imediatamente. O model da resposta nomeia o modelo que a criou (uma resposta de fala é o próprio arquivo de áudio: Atividade mostra seu modelo). Uma solicitação com quote_id não usa models, e uma transcrição não usa nenhum dos dois.

"provider": {"max_price": 0.05} é o máximo que uma unidade (o unit de precificação do modelo: imagem, segundo, megapixel, minuto, 1K caracteres ou solicitação) pode custar, em dólares americanos. Um modelo acima disso é recusado com 400 max_price_exceeded, e a solicitação nunca é cobrada acima de max_price vezes suas unidades. Outras opções de provider são recusadas com 400 unsupported_routing_option, porque a escolha do vendedor para solicitações de mídia não pode ser direcionada por solicitação.

"model": "best-price:image" (ou image-edit, text-to-video, image-to-video, music, speech, transcription) escolhe o modelo ativo mais barato para o trabalho; fastest: o mais rápido medido. Veja Apelidos de modelo.

Tags

"metadata": {"project": "spring-ads"} (até 16 valores de texto) é armazenado com o trabalho, retornado em seu status, exibido em Atividade e na exportação CSV, e nunca enviado a um modelo. Em uma transcrição, envie-os como campos de formulário: -F "metadata[project]=spring-ads". Veja Tags.

Defina um teto

Envie "max_cost" (dólares americanos, ex. 0.50) com qualquer solicitação de imagem, vídeo, música ou fala (um campo de formulário em uma transcrição). Se puder custar mais do que isso, é recusado com 400 max_cost_too_low e nada é cobrado. Para um trabalho de vídeo ou música, o teto exato é definido quando o trabalho começa; se então exceder seu max_cost, o trabalho é cancelado sem custo. Com "validate": true, a cotação adiciona within_max_cost.

Tentar novamente sem pagar duas vezes

Envie um cabeçalho Idempotency-Key (qualquer string única de até 255 caracteres, como um UUID) ao iniciar um trabalho de vídeo ou música. Se sua conexão cair e você enviar a mesma solicitação novamente com a mesma chave dentro de 24 horas, você recebe o mesmo trabalho de volta em vez de um segundo. A mesma chave com uma solicitação diferente é recusada com 409 idempotency_key_reused. Solicitações de imagem, fala e transcrição não usam uma chave: uma que falhou não foi cobrada, então envie-a novamente.

Seu saldo

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 está reservado para solicitações ainda em andamento; ele volta (menos o custo real) quando elas terminam. available_usd é o que novas solicitações podem usar.

Opções de cada modelo

GET /v1/models?type=image (ou video, music, speech, transcription, audio para ambos, chat, all; vários unidos por vírgulas; sem type a lista é apenas de modelos de chat) lista os modelos que você pode chamar agora, cada um com seu type, o endpoints para enviá-lo e seu pricing. GET /v1/models/<model id> fornece um modelo, e para um modelo de mídia, um objeto parameters: um JSON Schema do corpo da requisição com os comprimentos de clipe, resoluções, proporções e tamanhos que ele aceita, e qual imagem de origem ele precisa.

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

pricing tem usd (o máximo que um unit custa agora) e list_usd (o preço próprio do criador do modelo); um modelo de chat tem input_usd, output_usd e seus preços list_ por 1M tokens.

usd é o preço cotado agora para uma requisição simples do modelo: o vendedor para o qual sua requisição seria enviada com uma chave definida como Balanced (o padrão), incluindo nossa taxa. As listas e a cotação são calculadas pelo mesmo código e acompanham nossos vendedores em cerca de 30 segundos (um vendedor pausado, desativado ou com preço alterado).

Um modelo precificado por resolução também tem resolutions: uma linha por resolução (480p / 720p / 1080p de um vídeo, 1K / 2K / 4K de uma imagem), do mais barato primeiro, cada com usd (o que um segundo, ou uma imagem, nessa resolução é cotado) e list_usd. usd acima é a linha mais barata. Um clipe é cobrado pelo preço da resolução que ele solicita, multiplicado pelos seus segundos:

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

Alguns vendedores precificam um clipe inteiro, não por segundo. Tal linha também tem seconds: o comprimento do clipe cujo usd é o preço por segundo. É a taxa mais cara (o clipe mais curto do modelo), então um clipe mais longo custa menos que usd vezes seus segundos, e uma requisição que não especifica comprimento é cotada exatamente usd vezes seconds. seconds também aparece onde uma resolução é vendida em um único comprimento.

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

Um preço por segundo é arredondado para o $0.000001 mais próximo. Para o preço exato de uma requisição, peça uma cotação ("validate": true).

Erros

HTTP código significado
400 wrong_endpoint por exemplo, um modelo de imagem enviado para /v1/video/generations, um modelo de chat enviado para uma rota de imagem, ou um modelo de fala enviado para /v1/audio/transcriptions; a mensagem indica o caminho correto. Nada é cobrado, e a Atividade o lista como recusado
400 invalid_request a requisição está errada (a mensagem diz o porquê, por exemplo, uma duração que o modelo não oferece ou uma imagem de origem ausente)
400 image_required uma edição, ou um modelo de imagem para vídeo ou de referência para vídeo, sem imagem de origem
400 max_cost_too_low pode custar mais do que seu max_cost; nada foi cobrado
400 timestamps_unavailable srt, vtt ou verbose_json solicitados a um modelo de transcrição que não enviou marcações de tempo; nada foi cobrado
409 idempotency_key_reused esse Idempotency-Key foi usado para uma requisição diferente
400 quote_mismatch / quote_expired a requisição não é a orçada, ou o orçamento tem mais de 15 minutos
404 quote_not_found nenhum orçamento assim na sua conta
409 quote_used esse orçamento já iniciou uma requisição
400 max_price_exceeded o modelo custa mais por unidade do que seu provider.max_price
400 unsupported_routing_option uma opção de provider diferente de max_price
404 file_not_found nenhum arquivo carregado assim na sua conta, ou ele expirou
413 file_too_large um upload acima de 10 MB
429 too_many_files 500 uploads já estão armazenados; exclua alguns ou espere que expirem
503 files_unavailable uploads não estão disponíveis no momento
413 request_too_large a requisição excede o limite de tamanho (40 MB); envie imagens como links https:// e divida gravações longas
402 insufficient_credits seu saldo não pode cobrir o custo máximo do trabalho; a mensagem diz quanto é necessário
404 model_not_found / not_found nenhum modelo assim, ou nenhum trabalho assim na sua conta
404 artifact_expired o arquivo não está mais armazenado (veja acima)
429 rate_limited espere os segundos em Retry-After (alguns segundos se estiver ausente), então tente novamente; X-RateLimit-Remaining mostra quantas requisições restam neste minuto
503 no_available_provider nenhum fornecedor pode fazê-lo agora; MartLLM já tentou os outros. A mensagem nomeia os modelos do mesmo tipo que funcionam agora