NuevoCómo detectamos a un vendedor que ofrece el modelo equivocado, y te reembolsamos si pasa.
MartLLMantes UberLLM

Imágenes, vídeo, música y voz

La clave que usas para texto también crea imágenes, vídeos, música y voz, y convierte grabaciones en texto, desde el mismo saldo. Elige un modelo en la tabla de modelos (o ?type=image, ?type=music, ?type=audio); la página de cada modelo muestra su precio, su tipo y una solicitud de ejemplo funcional.

Quieres Ruta La imagen de origen va en
Una nueva imagen a partir de un prompt POST /v1/images/generations (ninguno)
Una imagen editada POST /v1/images/edits image (o image_url, input_images, images)
Un vídeo a partir de un prompt POST /v1/video/generations (ninguno)
Un vídeo que empieza con una imagen POST /v1/video/generations image_url (primer fotograma); end_image_url para el último fotograma
Un vídeo a partir de imágenes de referencia POST /v1/video/generations input_images con "role": "reference"
Una respuesta de texto sobre una imagen POST /v1/chat/completions una parte image_url en messages[].content
Música POST /v1/music/generations (ninguno)
Voz a partir de texto POST /v1/audio/speech (ninguno)
Texto a partir de una grabación POST /v1/audio/transcriptions (ninguno; la grabación va en file)

Una imagen de origen es un enlace https://, una URI data: (data:image/png;base64,iVBORw0…) o base64 simple de un PNG, JPEG o WebP, hasta 8 por solicitud. Las rutas de imagen también aceptan una carga multipart (abajo). Los enlaces deben ser enlaces públicos https://; los enlaces http:// son rechazados. Un enlace que redirige (por ejemplo, https://picsum.photos/640/360) es seguido, hasta 5 veces y solo a otros enlaces públicos https://, y el modelo obtiene el enlace al que llega. Un enlace que no lleva a una imagen, o redirige a un lugar que no podemos usar, es rechazado con 400 invalid_image_url antes de que se retenga o cobre nada. Las imágenes enviadas en línea hacen la solicitud más grande: mantenla por debajo de 10 MB, o envía enlaces.

En un mensaje de chat (image_url en messages[].content), un enlace (https:// o http://) es abierto por MartLLM y enviado al modelo como una URL data:, porque la mayoría de los modelos de visión solo aceptan eso. Cada imagen puede ser de hasta 20 MB (40 MB por solicitud), y las redirecciones se siguen hasta 5 veces, solo a direcciones públicas. Los modelos Gemini obtienen el enlace tal cual. Un enlace que no lleva a una imagen es rechazado con 400 invalid_image_url, y no se cobra nada.

Crear una imagen

Las imágenes se devuelven en la respuesta.

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 es lo que costó la imagen (también en el encabezado X-UberLLM-Cost-USD). En la rara respuesta donde el precio aún no se conoce, es null. Pagará lo que el proveedor cobró, nunca más de max_cost_usd, lo que se retuvo para ello.

response_format es url por defecto, tanto para /v1/images/generations como para /v1/images/edits. Envíe "response_format": "b64_json" para obtener la imagen dentro de la respuesta en su lugar. Cuando el modelo devuelve la imagen en sí, MartLLM la guarda como un archivo de su cuenta durante 24 horas y responde con su enlace (https://api.martllm.com/v1/files/file_…/content), que también funciona como la imagen fuente para una edición posterior. Descargue una URL con la misma clave:

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

n es 1 a 10.

Editar una imagen

Usa un modelo que edite (su ID suele terminar en -edit) y envía la imagen de origen en 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"}'

La misma imagen puede enviarse como:

  • "image": "data:image/png;base64,iVBORw0…"
  • "image_url": "https://…"
  • "input_images": ["https://…", "https://…"]: la primera es la imagen a editar, el resto son referencias. Una entrada también puede ser {"url": "…", "role": "reference"}.
  • "images": [{"image_url": "https://…"}], el formato que envían los SDK de OpenAI

También funciona base64 simple, y "input_image" se lee como "image".

O sube el archivo, como con la edición de imágenes de 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]

Una edición sin imagen de origen es rechazada con 400 image_required. Las máscaras (inpainting) no son compatibles.

Sube una imagen una vez

Sube una imagen a /v1/files y úsala en tantas solicitudes como quieras durante 24 horas, en lugar de enviarla en cada solicitud:

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

Luego, coloca el ID, o el url, dondequiera que vaya una imagen de origen: "image": "file_3f9c…", "image": {"file_id": "file_3f9c…"}, "image_url": "file_3f9c…", una entrada de input_images, o el fotograma inicial de un video. Solo tu cuenta puede usar sus archivos.

  • PNG, JPEG, WebP, GIF, HEIC o AVIF, hasta 10 MB cada una, con un máximo de 500 guardadas por cuenta a la vez.
  • Se guardan durante 24 horas, luego se eliminan. GET /v1/files/{id} describe una, GET /v1/files/{id}/content la descarga, DELETE /v1/files/{id} la elimina ahora.

Hacer un video

Un video tarda un minuto o más, por lo que es un trabajo: iniciarlo, comprobar su estado, descargarlo.

1. Iniciarlo

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 es opcional: modelos de respaldo que se prueban en orden solo cuando el primero no tiene un proveedor disponible en este momento, para que un momento de alta demanda no falle su solicitud (ver Modelos de respaldo). El video de arriba tarda aproximadamente un minuto y cuesta alrededor de $0.33.

Para empezar desde una imagen, use un modelo de imagen a video y añada 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}'

Un modelo que combina dos imágenes también toma end_image_url (el último fotograma). Un modelo de imagen a video o de referencia a video que no puede crear video solo a partir de texto es rechazado con 400 image_required cuando la solicitud no tiene imagen, antes de que se cobre algo. Un modelo de referencia a video toma las imágenes en 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}'

Otros campos, donde el modelo los ofrece: resolution (480p, 720p, 1080p…), aspect_ratio (16:9, 9:16, 1:1…) y audio (true / false; a un modelo sin configuración de sonido no se le envía y crea el clip como siempre lo hace).

Un modelo de imagen a video cuyo esquema no lista aspect_ratios (la mayoría de los modelos de imagen a video de Kling, Veo, Wan y Seedance) crea el clip con la forma de su imagen de origen. Envíele una imagen que ya tenga la forma que desea (recorte a 9:16 para un clip vertical) y omita aspect_ratio. Una forma enviada a dicho modelo es respondida con 400 invalid_request antes de que se cobre algo ("aspect_ratio": "auto" es aceptado y significa lo mismo que omitirlo).

Un modelo de referencia a video necesita una forma, por lo que cuando omite aspect_ratio se envía como 16:9 (o la primera forma del modelo si no crea 16:9); el esquema del modelo muestra ese valor predeterminado. Las opciones de cada modelo se listan por GET /v1/models/<model id> (ver Opciones de cada modelo).

Cada modelo crea solo ciertas duraciones de clip, resoluciones y formas. Una solicitud para uno que no crea es rechazada con un mensaje que lista los que sí crea, antes de que se cobre algo.

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 es el modelo que tomó el trabajo (un respaldo de models cuando el primero no pudo). Los costos que terminan en _usdc están en millonésimas de dólar (327250 = $0.33). estimated_cost_usd es el precio esperado. Comienza como el precio listado de lo que solicitó (los números validate y POST /v1/quote responden como cost_usd: el precio actual del modelo multiplicado por los segundos a la resolución solicitada, imágenes u otras unidades). Cuando el vendedor que toma el trabajo espera cobrar más que eso por su solicitud exacta, estimated_cost_usd es la cifra de ese vendedor en su lugar: generalmente a partir de esta primera respuesta, y a más tardar en un GET posterior de un trabajo que aún está en curso (algunos trabajos obtienen su vendedor unos segundos después de que comienzan, y un trabajo movido a otro vendedor toma el precio de ese vendedor). Solo sube, nunca más allá de max_cost_usd. El trabajo se factura por lo que el proveedor cobró por él: generalmente la estimación o menos, y en casos raros más (un clip hecho de una imagen cuyo precio el vendedor solo establece cuando termina). max_cost_usd es lo que se retiene de su saldo para el trabajo: la misma cifra mientras se ejecuta y después de que termina, y lo máximo que se factura el trabajo. Ningún trabajo se factura nunca por encima de eso, incluso cuando el vendedor que lo inició lo pierde y otro se hace cargo: un vendedor que costaría más que su max_cost_usd no se utiliza. Un modelo de video cuyo precio es por second se factura por segundo del clip; uno con precio por job cuesta eso por video.

2. Comprobarlo cada 5–10 segundos:

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

HTTP 202 mientras el trabajo se ejecuta, HTTP 200 una vez 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 }
}

El modelo informa el cargo exacto de un trabajo un poco después de que el archivo esté listo, generalmente dentro de 30 segundos. Hasta entonces, un trabajo succeeded muestra "usage": { "cost_usd": null, "cost_pending": true }; pregunte de nuevo unos segundos después. Si el cargo no ha llegado dentro de 30 minutos, el trabajo se factura a su precio listado (estimated_cost_usd) y usage.cost_note lo indica.

3. Descargarlo

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

Pida detener un trabajo que ya no necesita: DELETE /v1/video/generations/<job id>. Pedimos al proveedor que lo detenga; un trabajo que ya había hecho se factura como de costumbre, y uno que detiene termina canceled y no cuesta nada.

Modelos de vídeo de Fal

Los modelos cuyo ID empieza por fal-ai/ funcionan en Fal, por debajo del precio propio de Fal: pagas el precio de Fal menos el descuento del vendedor de Fal más barato en el marketplace ahora mismo (15% de descuento en 30 de octubre de 2026; 25% de descuento siempre que ese vendedor esté vendiendo). El precio se fija por lo que pides — segundos × la tarifa para la resolución, y si el clip tiene sonido — así que el coste del trabajo se conoce cuando empieza y estimated_cost_usd es exactamente lo que se factura. Un trabajo fallido no cuesta nada. Detener uno es un esfuerzo de buena fe: si Fal ya ha creado el clip, se factura.

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

Precio propio de Fal por segundo (el tuyo es este menos el descuento en vivo; la página de cada modelo, GET /v1/models y POST /v1/quote muestran el precio exacto ahora):

Modelo Duración (s) Precio de Fal por segundo, desde
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 · con sonido $0.126
fal-ai/kling-video/v3/pro/text-to-video, …/image-to-video 3–15 $0.112 · con sonido $0.168
fal-ai/kling-video/o3/standard/text-to-video, …/image-to-video 3–15 $0.084 · con sonido $0.112
fal-ai/kling-video/v2.6/pro/text-to-video, …/image-to-video 5, 10 $0.07 · con sonido $0.14
fal-ai/veo3.1/fast, fal-ai/veo3.1/fast/image-to-video 4, 6, 8 720p/1080p $0.10 · con sonido $0.15 · 4k $0.30
fal-ai/veo3.1, fal-ai/veo3.1/image-to-video 4, 6, 8 720p/1080p $0.20 · con sonido $0.40 · 4k $0.40
fal-ai/veo3.1/lite 4, 6, 8 720p $0.03 · con sonido $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 (imagen) $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 precio es propio de Fal; el descuento se aplica cuando el trabajo empieza. Si el vendedor más barato rechaza un trabajo, uno más caro lo realiza y el trabajo se factura al precio de ese vendedor, nunca más de estimated_cost_usd en la respuesta.

Algunos modelos nos cuestan menos de lo que indica el descuento del vendedor. Cada 6 horas comparamos lo que el marketplace nos cobró por cada modelo durante los últimos 7 días con el precio de Fal para los mismos trabajos. Un modelo con al menos 20 trabajos en ese tiempo se valora entonces a esa cuota real más 5%, cuando esta es inferior. La página del modelo, /v1/models y la factura utilizan el mismo precio. Si esa cifra tiene más de 3 días, el descuento del vendedor se aplica de nuevo.

Los campos son nuestros: duration_seconds, resolution, aspect_ratio, audio y image_url (o input_images). La propia ortografía de Fal (duration, generate_audio, start_image_url) también funciona. Kling, Veo y Kling 2.6 añaden sonido a menos que envíes "audio": false.

Estado del trabajo

status HTTP Significado
queued 202 Aceptado, esperando a que un modelo lo inicie
running 202 En creación; progress pasa de 0 a 1 cuando el modelo lo reporta
succeeded 200 Terminado; descarga results[].url
failed 200 No se creó. error.message explica por qué; error.retryable indica si volver a intentarlo puede funcionar
canceled 200 Detenido antes de crearse
expired 200 No terminó a tiempo

Estos seis son los únicos valores. failed, canceled y expired no cuestan nada. Un DELETE es una solicitud para detener el proceso, no una promesa: un trabajo que el proveedor termine de todos modos finaliza como succeeded y se factura.

Si el servicio está ocupado, se reintenta por ti. Cuando ningún proveedor está libre para crear tu video, o alguno está demasiado ocupado en ese momento, MartLLM reinicia el trabajo por su cuenta, hasta dos veces más en un plazo de 10 minutos. Mantiene el mismo job id y el mismo costo máximo. El trabajo simplemente tarda un poco más. Solo verás failed cuando hayan fallado todos los intentos, y un trabajo fallido no cuesta nada.

Espera. Envía callback_url y te avisaremos cuando termine el trabajo (consulta Callbacks), o consulta la poll URL cada 5–10 segundos. La mayoría de los videos tardan 1–5 minutos; algunos trabajos largos o de 4K tardan más. No tienes que consultar continuamente para que se cierre el cobro: un trabajo que nadie consulta se completa y se factura (o se reembolsa) igualmente por MartLLM, y aparece en Dashboard → API Keys → API Usage.

Callbacks

Añade callback_url a un trabajo de vídeo o música: un enlace https:// en un host público. Cuando el trabajo haya terminado definitivamente, MartLLM le envía un POST con el mismo JSON que GET devuelve sobre el trabajo.

{ "model": "kling/kling-o3", "prompt": "a red ball bouncing", "duration_seconds": 5,
  "callback_url": "https://your-app.example/uberllm/jobs" }
  • Cuándo. Una vez, cuando el trabajo haya terminado y su factura sea final: succeeded con usage.cost_usd establecido (nunca cost_pending), o failed, canceled o expired (coste 0). No se envía de nuevo cuando llega el coste, porque solo se envía después. Con output_upload_url también, el callback llega después de que la subida esté hecha, así que output_upload.status ya está delivered o failed.
  • Cabeceras. Content-Type: application/json, MartLLM-Event: job.succeeded (o job.failed, job.canceled, job.expired), UberLLM-Event-Id: <job id>:<status> y UberLLM-Signature: t=<unix seconds>,v1=<hex>.
  • Reintentos. Responde con cualquier 2xx en 15 segundos. Cualquier otra respuesta, o ninguna respuesta, se intenta de nuevo después de 30 segundos, 2 minutos, 10 minutos, 30 minutos y 2 horas, y luego se abandona. Aun así, puedes consultar el estado del trabajo en cualquier momento.
  • Repeticiones. Un mensaje puede llegar más de una vez (por ejemplo, cuando tu respuesta se pierde). El ID del evento permanece igual, así que descarta los que ya hayas procesado.
  • Estado. El trabajo muestra cómo fue: "callback": { "status": "delivered", "attempts": 1, "http_status": 200, "delivered_at": 1792540990 }. status es pending, delivered o failed (con error en palabras sencillas).
  • El enlace debe ser https:// en un host público, sin nombre de usuario ni contraseña. Nunca se muestra de vuelta y se elimina una vez que el callback finaliza. webhook_url se lee como el mismo campo. Las imágenes y el habla no lo toman: vuelven en la propia respuesta.

Comprueba la firma

Cada mensaje está firmado con el secreto de webhook de tu cuenta. Encuéntralo en Dashboard → API keys → Webhook signing secret; se crea la primera vez que lo abres, y Reemplazar secreto lo cambia al instante.

v1 es el HMAC-SHA256 hexadecimal de <t>.<raw body>, cifrado con el secreto completo (whsec_…). Calcúlalo sobre los bytes en bruto que recibiste (antes de analizar el JSON), compara en tiempo constante y rechaza un t de más de 5 minutos de antigüedad.

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 a un webhook

Los correos de alerta también pueden ir a un webhook: establece un enlace en Dashboard → Credits → For developers: also send alerts to a webhook, o PUT /api/v1/billing/alerts {"alerts_webhook_url": "https://…"} (null lo desactiva). Los mensajes se firman, reintentan e identifican de la misma manera que los callbacks. El cuerpo es:

{ "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: el saldo cayó por debajo de la cantidad que estableciste para el correo de saldo bajo. Se envía una vez cada vez que cae por debajo; no se envía nada hasta que establezcas una cantidad.
  • hold.not_released: el dinero reservado para un trabajo seguía retenido más de 15 minutos después de que el trabajo terminara. data.jobs los enumera (id, kind, model, ended_at, held_usd) y data.held_usd es el total. El dinero sigue siendo tuyo y nuestro equipo ha sido informado.

Cuánto tiempo se guardan los archivos

Descarga un resultado poco después de que se genere:

  • Los archivos de vídeo y música se guardan durante aproximadamente 3 horas después de que finalice el trabajo.
  • Los enlaces de imagen a /v1/media/artifacts/… se guardan durante aproximadamente 15 minutos; los enlaces de imagen a /v1/files/… durante 24 horas. Pide "response_format": "b64_json" para obtener la imagen dentro de la respuesta y guardarla tú mismo.
  • Las imágenes que subes a /v1/files se guardan durante 24 horas.

Después de eso, la descarga responde 404 artifact_expired.

Envía los resultados a tu propio almacenamiento

Añade output_upload_url a un trabajo de vídeo o música: un enlace https:// que acepte un HTTP PUT, como un enlace de subida presignado de S3, R2 o de Google Cloud Storage. Cuando el trabajo finaliza con éxito, MartLLM sube el archivo allí con su tipo de contenido. Para un trabajo que genera varios archivos, envía output_upload_urls, un enlace por archivo en orden (como 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=…" }

El estado del trabajo entonces tiene output_upload:

"output_upload": { "status": "delivered", "attempts": 1, "delivered_at": 1792540990,
  "files": [{ "artifact_index": 0, "http_status": 200, "bytes": 5242880 }] }
  • status está pending hasta que la subida se completa, luego delivered o failed (con error en palabras sencillas).
  • Un intento de subida fallido se vuelve a intentar después de 30 segundos, 2, 10 y 30 minutos, luego se marca failed; el archivo aún se puede descargar desde results[].url mientras se guarda. Haz que el enlace sea válido durante al menos una hora.
  • El enlace debe ser https:// en un host público, sin nombre de usuario ni contraseña. Nunca se muestra de vuelta, y se elimina una vez que finaliza la subida.
  • Las imágenes no lo aceptan: una imagen vuelve en la propia respuesta.

Música

Los mismos tres pasos en /v1/music/generations. curl -OJ guarda la pista con el nombre de archivo que enviamos.

Voz

Se introduce texto y se obtiene un archivo de audio como respuesta.

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

También puedes enviar voice, response_format (por ejemplo mp3 o wav) y speed. Cada modelo tiene sus propias voces (GET /v1/models/{id} las enumera). Con best-price:speech o fastest:speech no sabes de antemano qué modelo se utiliza, por lo que la voz se adapta a él: se mantiene una voz que el modelo tenga, los nombres de OpenAI se asignan a la voz coincidente del modelo donde la tenga (alloy → af_alloy), y cualquier otra voz, o ninguna, obtiene la primera voz del modelo. Cuando nombras un modelo, tu voz se envía tal cual. Se factura por cada 1K caracteres iniciados de input. La respuesta es el archivo de audio; su encabezado X-UberLLM-Cost-USD indica el coste, y X-Request-Id es el ID de la solicitud tal como aparece en Actividad. "validate": true, max_cost, metadata, models y provider.max_price funcionan como en las imágenes (consulta Lo que pagas).

Convertir una grabación en texto

Envía la grabación como un formulario con file y 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 es lo que cuesta (también en el encabezado X-UberLLM-Cost-USD, el único lugar para las respuestas text, srt y vtt). Nuestros propios campos también van en el formulario y nunca se envían al modelo: -F max_cost=0.10, -F "metadata[project]=podcast", -F validate=true.

También puedes enviar language, prompt, temperature y response_format:

response_format Obtienes
json (el predeterminado) { "text": …, "duration": …, "usage": … }
text las palabras como texto plano
srt un archivo de subtítulos con tiempos (SubRip), listo para un editor de vídeo o un anuncio
vtt los mismos subtítulos que WebVTT
verbose_json la respuesta json más segments (id, start, end, text, en segundos) y, en un modelo que temporiza palabras individuales, 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 da un subtítulo por frase; elevenlabs/elevenlabs-scribe-v2 temporiza cada palabra, y sus subtítulos se cortan en líneas de un máximo de 42 caracteres, una nueva después de cada frase. Si un modelo no envía tiempos para una grabación, srt, vtt y verbose_json responden 400 timestamps_unavailable y no se cobra nada. Se factura por minuto de audio, sea cual sea el formato. Los archivos pueden ser de hasta 40 MB. El formato (mp3, wav, ogg, flac, m4a/mp4, webm, aac) se lee de la propia grabación, no de su nombre de archivo, por lo que una subida llamada tmp123.out funciona.

Con el SDK de OpenAI

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)

Lo que pagas

  • El precio de lo que se hizo: lo que el proveedor cobró, sin tarifa de MartLLM. Una respuesta de imagen o transcripción y un trabajo terminado lo llevan como usage.cost_usd (dólares estadounidenses); cada respuesta que produjo algo también lo lleva en el encabezado de respuesta X-UberLLM-Cost-USD (para voz, el encabezado es el único lugar, ya que la respuesta es el archivo de audio). Se muestra en Dashboard → Activity. El resto de la retención se devuelve.
  • Nada por un trabajo que failed, fue canceled o expired, o por una solicitud de imagen, voz o transcripción que falla.
  • El vendedor más barato que hace exactamente lo que pediste. Muchos modelos de imagen y video tienen más de un vendedor; cada solicitud va al más barato que puede hacerlo con tu configuración, y a otro si ese no puede aceptarla. La lista de modelos y cada página de modelo muestran el precio del vendedor más barato disponible ahora.
  • La configuración de enrutamiento de tu API key (Dashboard → API keys) elige entre vendedores cuando uno es más rápido: Precio más bajo siempre toma el más barato, el predeterminado también toma el más barato a menos que siga fallando o sea más del doble de lento que el más rápido, Equilibrado toma el más barato que es como máximo 20% más lento que el más rápido, y Más rápido toma el más veloz, hasta el precio listado del modelo. Una cotización y el estimated_cost_usd del trabajo muestran el precio del vendedor que tu configuración elige. Ver Configuración de enrutamiento de tu API key.
  • Consulta tu saldo y lo que está retenido con GET /v1/balance (abajo).

Verifica el precio antes de gastar

Añade "validate": true a cualquier solicitud de imagen, video, música o voz (para una transcripción, envía validate=true como un campo de formulario con la grabación). La solicitud se verifica como si fuera real (model, options, source pictures), no se produce nada y no se cobra nada, y HTTP 200 indica lo que cuesta al precio listado (cost_usd, el precio que se muestra en la página del modelo; pagas lo que el proveedor cobró, que puede diferir) y lo que se retiene mientras se ejecuta (max_cost_usd, lo máximo que se factura):

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

Si el vendedor del modelo necesita una configuración que omitiste (un modelo de referencia a video necesita aspect_ratio), el valor predeterminado con el que se envía se muestra en el schema del modelo y en la cotización como defaults_applied, p. ej. "defaults_applied": {"aspect_ratio": "16:9"}.

Una solicitud que sería rechazada se rechaza de la misma manera, con la razón.

Retener un precio por 15 minutos

POST /v1/quote toma el mismo body que la solicitud de imagen, video, música o voz y responde con el costo listado (cost_usd), lo que se retiene mientras se ejecuta (max_cost_usd, lo máximo que se factura) y un quote_id (para una transcripción, envía model y duration_seconds; una transcripción en sí misma no toma quote_id, usa max_cost para limitarla):

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

Envía la misma solicitud con "quote_id": "6f1c…" dentro de 15 minutos y se factura lo que el proveedor cobró, como máximo max_cost_usd; si lo que debe retenerse al iniciar es superior a max_cost_usd, se cancela sin cargo. No se cobra ni se retiene nada por la cotización en sí.

  • Una cotización inicia una solicitud. Usarla de nuevo responde 409 quote_used; un trabajo que nunca llegó a un modelo devuelve la cotización.
  • La solicitud debe pedir lo mismo: el mismo model y la misma configuración (prompt, size, clip length, source pictures …). Cualquier otra cosa se rechaza con 400 quote_mismatch. max_cost, metadata y output_upload_url pueden diferir.
  • Después de 15 minutos responde 400 quote_expired. Los modelos de chat se facturan por token y no tienen cotización: limítalos con provider.max_price.

Modelos de respaldo y un límite de precio

"models": ["model-b", "model-c"] nombra modelos a intentar en orden cuando el primero no puede ser atendido en este momento (no_available_provider) o está por encima de tu provider.max_price. Cualquier otro rechazo se responde de inmediato. El model de la respuesta nombra el modelo que lo hizo (una respuesta de voz es el archivo de audio en sí: Activity muestra su modelo). Una solicitud con quote_id no toma models, y una transcripción tampoco.

"provider": {"max_price": 0.05} es lo máximo que una unidad (el unit de precios del modelo: imagen, segundo, megapixel, minute, 1K caracteres o request) puede costar, en dólares estadounidenses. Un modelo por encima de este se rechaza con 400 max_price_exceeded, y la solicitud nunca se factura por encima de max_price veces sus unidades. Otras opciones de provider se rechazan con 400 unsupported_routing_option, porque la elección del vendedor para solicitudes de medios no puede dirigirse por solicitud.

"model": "best-price:image" (o image-edit, text-to-video, image-to-video, music, speech, transcription) elige el modelo en vivo más barato para el trabajo; fastest: el más rápido medido. Ver Alias de modelos.

Etiquetas

"metadata": {"project": "spring-ads"} (hasta 16 valores de texto) se almacena con el trabajo, se devuelve en su status, se muestra en Activity y en la exportación CSV, y nunca se envía a un modelo. En una transcripción, envíalos como campos de formulario: -F "metadata[project]=spring-ads". Ver Etiquetas.

Establecer un límite

Envía "max_cost" (dólares estadounidenses, p. ej. 0.50) con cualquier solicitud de imagen, video, música o voz (un campo de formulario en una transcripción). Si puede costar más que eso, se rechaza con 400 max_cost_too_low y no se cobra nada. Para un trabajo de video o música, el límite exacto se establece cuando el trabajo comienza; si luego resulta por encima de tu max_cost, el trabajo se cancela sin cargo. Con "validate": true, la cotización añade within_max_cost.

Reintentar sin pagar dos veces

Envía un encabezado Idempotency-Key (cualquier cadena única de hasta 255 caracteres, como un UUID) cuando inicies un trabajo de video o música. Si tu conexión se cae y envías la misma solicitud de nuevo con la misma key dentro de 24 horas, obtendrás el mismo trabajo de vuelta en lugar de uno segundo. La misma key con una solicitud diferente se rechaza con 409 idempotency_key_reused. Las solicitudes de imagen, voz y transcripción no toman una key: una que falló no fue cobrada, así que envíala de nuevo.

Tu 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 solicitudes aún en curso; vuelve (menos el costo real) cuando finalizan. available_usd es lo que pueden usar las nuevas solicitudes.

Opciones de cada modelo

GET /v1/models?type=image (o video, music, speech, transcription, audio para ambos, chat, all; varios unidos con comas; sin type la lista es solo de modelos de chat) enumera los modelos que puedes llamar ahora mismo, cada uno con su type, el endpoints al que enviarlo y su pricing. GET /v1/models/<model id> proporciona un modelo, y para un modelo de medios, un objeto parameters: un JSON Schema del cuerpo de la solicitud con las duraciones de los clips, resoluciones, relaciones de aspecto y tamaños que acepta, y qué imagen de origen necesita.

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

pricing tiene usd (lo máximo que cuesta un unit ahora) y list_usd (el precio propio del creador del modelo); un modelo de chat tiene input_usd, output_usd y sus precios list_ por 1M tokens.

usd es el precio cotizado ahora mismo para una solicitud simple del modelo: el vendedor al que iría tu solicitud con una clave configurada en Balanced (el valor predeterminado), incluyendo nuestra tarifa. Las listas y la cotización se calculan con el mismo código y siguen a nuestros vendedores en aproximadamente 30 segundos (un vendedor pausado, desactivado o con precio modificado).

Un modelo con precio por resolución también tiene resolutions: una fila por resolución (480p / 720p / 1080p de un video, 1K / 2K / 4K de una imagen), la más barata primero, cada una con usd (lo que se cotiza por un segundo, o una imagen, a esa resolución) y list_usd. usd arriba es la fila más barata. Un clip se factura al precio de la resolución que solicita, multiplicado por sus 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}]}

Algunos vendedores cotizan un clip completo, no por segundo. Tal fila también tiene seconds: la duración del clip cuyo usd es el precio por segundo. Es la tarifa más cara (el clip más corto del modelo), por lo que un clip más largo cuesta menos de usd veces sus segundos, y una solicitud que no especifica duración se cotiza exactamente usd veces seconds. seconds también aparece donde una resolución se vende con una sola duración.

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

Un precio por segundo se redondea al $0.000001 más cercano. Para el precio exacto de una solicitud, pide una cotización ("validate": true).

Errores

HTTP code meaning
400 wrong_endpoint p. ej. un modelo de imagen enviado a /v1/video/generations, un modelo de chat enviado a una ruta de imagen, o un modelo de voz enviado a /v1/audio/transcriptions; el mensaje indica la ruta correcta. No se cobra nada, y Actividad lo lista como rechazado
400 invalid_request la solicitud es incorrecta (el mensaje indica el motivo, p. ej. una duración que el modelo no ofrece o una imagen de origen faltante)
400 image_required una edición, o un modelo de imagen a video o de referencia a video, sin imagen de origen
400 max_cost_too_low puede costar más que tu max_cost; no se cobró nada
400 timestamps_unavailable srt, vtt o verbose_json solicitado a un modelo de transcripción que no envió tiempos; no se cobró nada
409 idempotency_key_reused ese Idempotency-Key fue usado para una solicitud diferente
400 quote_mismatch / quote_expired la solicitud no es la cotizada, o la cotización tiene más de 15 minutos
404 quote_not_found no existe tal cotización en tu cuenta
409 quote_used esa cotización ya inició una solicitud
400 max_price_exceeded el modelo cuesta más por unidad que tu provider.max_price
400 unsupported_routing_option una opción de provider diferente a max_price
404 file_not_found no existe tal archivo subido en tu cuenta, o ha expirado
413 file_too_large una subida de más de 10 MB
429 too_many_files ya se mantienen 500 subidas; elimina algunos o espera a que expiren
503 files_unavailable las subidas no están disponibles ahora mismo
413 request_too_large la solicitud supera el límite de tamaño (40 MB); envía las imágenes como enlaces https:// y divide las grabaciones largas
402 insufficient_credits tu saldo no puede cubrir el costo máximo del trabajo; el mensaje indica cuánto se necesita
404 model_not_found / not_found no existe tal modelo, o no existe tal trabajo en tu cuenta
404 artifact_expired el archivo ya no se mantiene (ver arriba)
429 rate_limited espera los segundos en Retry-After (unos pocos segundos si está ausente), luego reintenta; X-RateLimit-Remaining muestra cuántas solicitudes quedan este minuto
503 no_available_provider ningún proveedor puede hacerlo ahora mismo; MartLLM ya probó los demás. El mensaje nombra los modelos del mismo tipo que funcionan ahora