新我们如何抓出挂错模型的卖家,并在发生时为你退款。

图像、视频、音乐和语音

您用于文本的 API key 也能用于生成图像、视频、音乐和语音,并将录音转换为文本,所有这些都从同一个余额中扣除。在 模型表格 (或 ?type=image, ?type=music, ?type=audio) 中选择一个模型;每个模型的页面都会显示其价格、类型和可用的请求示例。

您想要 路由 来源图片放入
从提示生成新图像 POST /v1/images/generations (无)
编辑图片 POST /v1/images/edits image (或 image_url, input_images, images)
从提示生成视频 POST /v1/video/generations (无)
从图片开始的视频 POST /v1/video/generations image_url (第一帧);end_image_url 用于最后一帧
从参考图片生成视频 POST /v1/video/generations input_images 和 "role": "reference"
关于图片的文本回答 POST /v1/chat/completions messages[].content 中的 image_url 部分
音乐 POST /v1/music/generations (无)
从文本生成语音 POST /v1/audio/speech (无)
从录音生成文本 POST /v1/audio/transcriptions (无;录音放入 file)

来源图片可以是 https:// 链接、data: URI (data:image/png;base64,iVBORw0…) 或 PNG、JPEG 或 WebP 的纯 base64 编码,每次请求最大 8。图像路由也支持多部分上传(见下文)。链接必须是公共 https:// 链接;http:// 链接将被拒绝。重定向的链接(例如 https://picsum.photos/640/360)将被跟踪,最多 5 次,且仅限于其他公共 https:// 链接,模型将获取最终着陆的链接。如果链接未指向图片,或重定向到我们无法使用的位置,则会在扣费或保留任何内容之前,以 400 invalid_image_url 拒绝。内联发送图片会使请求变大:请将其保持在 10 MB 以下,或发送链接。

在聊天消息中(messages[].content 中的 image_url),MartLLM 会打开链接(https:// 或 http://),并将其作为 data: URL 发送给模型,因为大多数视觉模型只接受这种格式。每张图片最大可达 20 MB(每次请求 40 MB),重定向最多跟踪 5 次,且仅限于公共地址。Gemini 模型会按原样获取链接。如果链接未指向图片,则会以 400 invalid_image_url 拒绝,且不收取任何费用。

生成图片

图片会随回答一同返回。

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 是图片费用(也在 X-UberLLM-Cost-USD 标头中)。在极少数价格尚未知晓的回答中,费用为 null。您支付提供商收取的费用,绝不会超过 max_cost_usd,即为此预留的金额。

response_format 默认为 url,对于 /v1/images/generations 和 /v1/images/edits 都是如此。发送 "response_format": "b64_json" 以便在回答中获取图片。当模型返回图片本身时,MartLLM 会将其作为您账户的文件保存 24 小时,并返回其链接(https://api.martllm.com/v1/files/file_…/content),该链接也可作为后续编辑的源图片。使用相同的密钥下载 URL:

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

n 是 1 到 10。

编辑图片

使用一个编辑模型(其ID通常以 -edit 结尾),并将源图片发送到 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"}'

同一张图片可以作为以下形式传入:

  • "image": "data:image/png;base64,iVBORw0…"
  • "image_url": "https://…"
  • "input_images": ["https://…", "https://…"]:第一个是要编辑的图片,其余是参考图。一个条目也可以是 {"url": "…", "role": "reference"}。
  • "images": [{"image_url": "https://…"}],OpenAI SDKs 发送的格式

普通的 base64 也可以,并且 "input_image" 会被读取为 "image"。

或者上传文件,就像使用 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]

没有源图片的编辑请求会被 400 image_required 拒绝。不支持蒙版(局部填充)。

一次上传图片

将图片上传到 /v1/files,并在您喜欢的任意数量的请求中持续 24 小时使用它,而不是在每个请求中都发送它:

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

然后将 ID 或 url 放在任何需要源图片的地方:"image": "file_3f9c…"、"image": {"file_id": "file_3f9c…"}、"image_url": "file_3f9c…"、input_images 的一个条目,或视频的起始帧。只有您的账户才能使用其文件。

  • PNG、JPEG、WebP、GIF、HEIC 或 AVIF 格式,每张图片最大 10 MB,每个账户同时最多保留 500 张。
  • 保留 24 小时,然后删除。GET /v1/files/{id} 描述一个,GET /v1/files/{id}/content 下载它,DELETE /v1/files/{id} 立即删除它。

制作视频

视频制作需要一分钟或更长时间,因此这是一项任务:启动它、检查它、下载它。

1. 启动它

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 是可选的:仅当首选模型当前没有空闲提供商时,才会按顺序尝试备用模型,以免在高峰期您的请求失败(参见 备用模型)。上述视频大约需要一分钟,费用约为 $0.33。

要从图片开始,请使用图像转视频模型并添加 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}'

融合两张图片的模型也需要 end_image_url(最后一帧)。无法仅从文本制作视频的图像转视频或参考转视频模型,如果请求中没有图片,则会以 400 image_required 拒绝,且不收取任何费用。参考转视频模型在 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}'

其他字段,如果模型提供:resolution(480p、720p、1080p…)、aspect_ratio(16:9、9:16、1:1…)和 audio(true / false;没有声音设置的模型不会收到此设置,并会像往常一样制作片段)。

模式中未列出 aspect_ratios 的图像转视频模型(大多数 Kling、Veo、Wan 和 Seedance 图像转视频模型)会以您的源图片的形状制作片段。向其发送一张已具有所需形状的图片(垂直片段请裁剪为 9:16),并省略 aspect_ratio。发送给此类模型的形状会在收取任何费用之前以 400 invalid_request 回复("aspect_ratio": "auto" 被接受,其含义与省略相同)。

参考转视频模型需要一个形状,因此当您省略 aspect_ratio 时,它会作为 16:9 发送(如果模型不制作 16:9,则发送模型的第一个形状);模型的模式会显示该默认值。每个模型的选择都由 GET /v1/models/<model id> 列出(参见 每个模型的选项)。

每个模型只制作特定长度、分辨率和形状的片段。如果请求的模型不制作,则会以列出其支持的片段的消息拒绝,且不收取任何费用。

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 是接受该任务的模型(当首选模型无法处理时,来自 models 的备用模型)。以 _usdc 结尾的费用以百万分之一美元计(327250 = $0.33)。estimated_cost_usd 是预期价格。它最初是您请求内容的标价(数字 validate 和 POST /v1/quote 回复为 cost_usd:模型当前价格乘以请求分辨率下的秒数、图片或其他单位)。当接受任务的卖家预计对您的确切请求收取更高费用时,estimated_cost_usd 则是该卖家的数字:通常从首次回复开始,最迟在正在运行的任务的后续 GET 时(某些任务在启动几秒后才确定卖家,而转移到其他卖家的任务则采用该卖家的价格)。它只会上涨,绝不会超过 max_cost_usd。任务按提供商收取的费用计费:通常是估算值或更少,在极少数情况下会更多(例如,从图片制作的片段,卖家仅在任务结束时才设定价格)。max_cost_usd 是为该任务从您的余额中扣留的金额:在任务运行期间和结束后都是相同的数字,也是任务的最高计费金额。任何任务都不会超出此金额计费,即使启动任务的卖家丢失任务并由另一个卖家接管也是如此:费用超过您的 max_cost_usd 的卖家将不会被使用。价格按 second 计算的视频模型按片段的每秒计费;价格按 job 计算的模型则按每个视频收取该费用。

2. 检查它 每 5–10 秒:

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

HTTP 202 任务运行时,HTTP 200 任务结束后:

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

模型会在文件准备好后不久报告任务的确切费用,通常在 30 秒内。在此之前,succeeded 任务会显示 "usage": { "cost_usd": null, "cost_pending": true };几秒后请再次查询。如果 30 分钟内仍未收到费用,任务将按其标价(estimated_cost_usd)计费,并且 usage.cost_note 会说明这一点。

3. 下载它

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

请求停止您不再需要的任务:DELETE /v1/video/generations/<job id>。我们会要求提供商停止它;已制作完成的任务照常计费,而停止的任务则以 canceled 结束且不收取任何费用。

Fal 视频模型

id 以 fal-ai/ 开头的模型运行在 Fal 上,价格低于 Fal 自己的价格: 你支付的是 Fal 的价格减去当前市场上最便宜的 Fal 卖家提供的折扣后的金额 (在 2026年10月30日 减 15%;只要那个卖家在售,就减 25%)。价格由你所请求的内容决定——秒数 × 对应分辨率的费率,以及片段是否带声音——所以任务一开始成本就已知,账单金额正好是 estimated_cost_usd。失败的任务不收费。停止任务只能尽力而为:如果 Fal 已经生成片段,就会收费。

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 自己的每秒价格(你的价格是在此基础上减去实时折扣;每个模型的页面、GET /v1/models 和 POST /v1/quote 会显示当前的准确价格):

模型 时长(秒) Fal 每秒价格,起
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 · 带声音 $0.126
fal-ai/kling-video/v3/pro/text-to-video, …/image-to-video 3–15 $0.112 · 带声音 $0.168
fal-ai/kling-video/o3/standard/text-to-video, …/image-to-video 3–15 $0.084 · 带声音 $0.112
fal-ai/kling-video/v2.6/pro/text-to-video, …/image-to-video 5, 10 $0.07 · 带声音 $0.14
fal-ai/veo3.1/fast, fal-ai/veo3.1/fast/image-to-video 4, 6, 8 720p/1080p $0.10 · 带声音 $0.15 · 4k $0.30
fal-ai/veo3.1, fal-ai/veo3.1/image-to-video 4, 6, 8 720p/1080p $0.20 · 带声音 $0.40 · 4k $0.40
fal-ai/veo3.1/lite 4, 6, 8 720p $0.03 · 带声音 $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 (图片) $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

每个价格都是 Fal 自己的价格;任务开始时会在其基础上扣除折扣。如果最便宜的卖家拒绝任务,会有更贵的卖家来完成,任务按那个卖家的价格计费,回复中显示的金额绝不会超过 estimated_cost_usd。

有些模型我们的成本比卖家折扣所说的还低。每 6 小时,我们会把过去 7 天市场就每个模型向我们收取的费用,与 Fal 对相同任务的收费进行比较。如果某个模型在那段时间内至少有 20 个任务,就按那个实际占比加 5% 来定价,前提是这样更低。模型页面、/v1/models 和账单都使用同一个价格。如果那个数字已超过 3 天未更新,就再次应用卖家折扣。

这些字段是我们自己的:duration_seconds、resolution、aspect_ratio、audio 和 image_url(或 input_images)。Fal 自己的拼写(duration、 generate_audio、start_image_url)也可以。Kling、Veo 和 Kling 2.6 会添加声音, 除非你发送 "audio": false。

任务状态

status HTTP 含义
queued 202 已受理,正在等待模型启动
running 202 生成中;模型上报时,progress 会从 0 变为 1
succeeded 200 已完成;下载 results[].url
failed 200 未生成。error.message 会说明原因;error.retryable 会说明重试是否可行
canceled 200 在生成前已停止
expired 200 未在规定时间内完成

状态值仅有这六种。failed、canceled 和 expired 不收取任何费用。DELETE 是一项停止请求,并非绝对保证:如果供应商仍将任务完成,该任务最终仍为 succeeded 并会正常计费。

遇到繁忙时会自动为您重试。 当没有供应商空闲来生成您的视频,或者当前供应商太忙时,MartLLM 会在 10 分钟内自动重新启动任务最多两次。任务将保持相同的任务 ID 和相同的最高费用上限,只是耗时会稍长一些。只有在所有重试均告失败时,您才会看到 failed,而失败的任务不收取任何费用。

等待。 发送 callback_url,我们会在任务结束时通知您(参见回调),或者每隔 5–10 秒查询一次轮询 URL。大多数视频需要 1–5 分钟;部分较长或 4K 任务耗时更久。您无需为了完成结算而持续查询:即便无人查询,任务仍会由 MartLLM 正常完成并计费(或退款),并显示在控制台 → API Keys → API 用量中。

回调

为视频或音乐任务添加 callback_url:一个位于公共主机的 https:// 链接。当任务彻底结束后,MartLLM 会向其发送一个 POST,包含与 GET 返回的任务信息相同的 JSON。

{ "model": "kling/kling-o3", "prompt": "a red ball bouncing", "duration_seconds": 5,
  "callback_url": "https://your-app.example/uberllm/jobs" }
  • 何时。 一次,当任务结束且账单最终确定时:succeeded 且 usage.cost_usd 已设置(绝非 cost_pending),或 failed、canceled 或 expired(费用 0)。费用到达时不会再次发送,因为它只在之后发送。对于 output_upload_url 也是如此,回调会在上传完成后发送,因此 output_upload.status 已经处于 delivered 或 failed 状态。
  • 请求头。 Content-Type: application/json、MartLLM-Event: job.succeeded(或 job.failed、job.canceled、job.expired)、UberLLM-Event-Id: <job id>:<status> 和 UberLLM-Signature: t=<unix seconds>,v1=<hex>。
  • 重试。 在 15 秒内回复任意 2xx 状态码。任何其他回复,或无回复,将在 30 秒、2 分钟、10 分钟、30 分钟和 2 小时后重试,之后放弃。您仍然可以随时轮询任务状态。
  • 重复。 消息可能会多次到达(例如当您的回复丢失时)。事件 ID 保持不变,因此请丢弃您已处理过的消息。
  • 状态。 任务会显示其执行情况:"callback": { "status": "delivered", "attempts": 1, "http_status": 200, "delivered_at": 1792540990 }。status 为 pending、delivered 或 failed(error 为纯文本描述)。
  • 链接必须是位于公共主机上的 https:// 链接,其中不包含用户名或密码。它绝不会被回显,并在回调结束后删除。webhook_url 被读取为相同的字段。图像和语音不使用它:它们会在回复本身中返回。

检查签名

每条消息都使用您账户的 webhook 密钥进行签名。在 Dashboard → API keys → Webhook signing secret] 中查找;它在您首次打开时生成,点击 Replace secret 即可立即更换。

v1 是 <t>.<raw body> 的十六进制 HMAC-SHA256,使用完整的密钥(whsec_…)进行加密。在您收到的原始字节(解析 JSON 之前)上计算它,以恒定时间进行比较,并拒绝超过 5 分钟的 t。

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

通过 webhook 发送警报

警报邮件也可以发送到 webhook:在 Dashboard → Credits → For developers: also send alerts to a webhook] 下设置链接,或 PUT /api/v1/billing/alerts {"alerts_webhook_url": "https://…"}(null 表示关闭)。消息的签名、重试和识别方式与回调相同。消息体为:

{ "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:余额低于您为低余额警报邮件设置的金额。每次低于该金额时发送一次;在您设置金额之前不会发送任何内容。
  • hold.not_released:为任务预留的资金在任务结束后 15 分钟仍被保留。data.jobs 列出了它们(id、kind、model、ended_at、held_usd),data.held_usd 是总金额。这笔钱仍然属于您,我们的团队已收到通知。

文件保留时长

请在结果生成后尽快下载:

  • 视频和音乐文件在任务结束后会保留约 3 小时。
  • 指向 /v1/media/artifacts/… 的图片链接会保留约 15 分钟;指向 /v1/files/… 的图片链接会保留24 小时。请求 "response_format": "b64_json" 可将图片直接包含在回复中,方便您自行保存。
  • 您上传到 /v1/files 的图片会保留24 小时。

此后,下载请求会返回 404 artifact_expired。

将结果发送到您自己的存储空间

为视频或音乐任务添加 output_upload_url:这是一个接受 HTTP PUT 的 https:// 链接,例如预签名的 S3, R2 或 Google Cloud Storage 上传链接。任务成功后,MartLLM 会将文件及其内容类型上传到该链接。对于生成多个文件的任务,请发送 output_upload_urls,每个文件一个链接,按顺序排列(最多 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=…" }

任务状态将包含 output_upload:

"output_upload": { "status": "delivered", "attempts": 1, "delivered_at": 1792540990,
  "files": [{ "artifact_index": 0, "http_status": 200, "bytes": 5242880 }] }
  • status 在上传完成前为 pending,完成后变为 delivered 或 failed(并附有 error 的文字说明)。
  • 上传失败后,会在 30 秒、2, 10 和 30 分钟后重试,然后标记为 failed;文件在保留期间仍可从 results[].url 下载。请确保链接至少一小时内有效。
  • 该链接必须是公共主机上的 https://,不包含用户名或密码。它绝不会被回显,并在上传结束后立即删除。
  • 图片不接受此功能:图片会直接在回复中返回。

音乐

同样的三步在 /v1/music/generations。curl -OJ 将音轨保存为我们发送的文件名。

语音

文本输入,返回音频文件作为结果。

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

您还可以发送 voice、response_format(例如 mp3 或 wav)和 speed。 每个模型都有自己的语音(GET /v1/models/{id} 列出了它们)。使用 best-price:speech 或 fastest:speech 时,您无法提前知道使用了哪个模型, 因此语音会进行适配:模型自带的语音会被保留,OpenAI 的语音名称会映射到 模型中对应的语音(如果模型有的话)(alloy → af_alloy),任何其他语音,或 未指定语音时,则使用模型的第一个语音。当您指定模型时,您的语音会按原样发送。 费用按 input 每 1K 个字符(不足 1K 个字符按 1K 个字符计费)收取。返回结果是音频文件;它的 X-UberLLM-Cost-USD 头部会显示费用,而 X-Request-Id 是在“活动”中列出的请求 ID。 "validate": true、max_cost、metadata、models 和 provider.max_price 的作用与图像处理相同(参见 您需要支付的费用)。

将录音转换为文本

以包含 file 和 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 是其费用(也在 X-UberLLM-Cost-USD 标题中,这是 text、srt 和 vtt 答案的唯一位置)。我们自己的字段也包含在表单中,并且绝不会发送给模型:-F max_cost=0.10、-F "metadata[project]=podcast"、-F validate=true。

您还可以发送 language、prompt、temperature 和 response_format:

response_format 您将获得
json(默认) { "text": …, "duration": …, "usage": … }
text 纯文本形式的文字
srt 一个带有时间戳的字幕文件 (SubRip),可用于视频编辑器或广告
vtt 与 WebVTT 相同的字幕
verbose_json json 答案加上 segments(id、start、end、text,以秒为单位),以及在能对单个词进行计时的模型上,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 每句话提供一个字幕;elevenlabs/elevenlabs-scribe-v2 对每个词进行计时,其字幕被截断为最多 42 个字符的行,每句话后另起一行。如果模型未发送录音的时间戳,则 srt、vtt 和 verbose_json 返回 400 timestamps_unavailable,并且不收取任何费用。费用按每分钟音频计算,无论格式如何。文件最大可达 40 MB。格式(mp3,、wav、ogg、flac、m4a/mp4,、webm、aac)是从录音本身读取的,而不是从其文件名读取的,因此名为 tmp123.out 的上传文件也能正常工作。

使用 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)

你支付什么

  • 所生成内容的价格:提供商收多少就是多少,不收取 MartLLM 费用。图片或转写回答,以及已完成的任务,会以 usage.cost_usd(美元)体现这个价格;每个实际生成了内容的回答还会在 X-UberLLM-Cost-USD 响应头中带上它(对于语音,响应头是唯一的地方,因为回答就是音频文件)。它会显示在 仪表盘 → 活动 中。其余冻结金额会退回。
  • 对于 failed、曾为 canceled 或曾为 expired 的任务,或者失败的图片、语音或转写请求,均不收费。
  • 能完全按你的要求制作的最便宜卖家。许多图片和视频模型有不止一个卖家;每个请求都会交给能用你的设置完成它的最便宜卖家,如果那个卖家接不了,就交给另一个。模型列表和每个模型页面会显示当前最便宜卖家的实时价格。
  • 你的密钥的路由设置(仪表盘 → API keys)会在某个卖家更快时决定选哪个卖家:最低价格总是选最便宜的,默认设置也选最便宜的,除非它持续失败,或耗时超过最快卖家的两倍;均衡选最便宜且比最快的慢不超过 20% 的,最快选最快的,最高到模型的标价。报价和任务的 estimated_cost_usd 会显示你的设置所选卖家的价格。参见 你的密钥的路由设置。
  • 用 GET /v1/balance(见下方)查看你的余额和冻结金额。

花钱前先查价格

在任何图片、视频、音乐或语音请求中加入 "validate": true(对于转写,把 validate=true 作为表单字段随录音发送)。这个请求会像真实请求一样被检查(模型、选项、源图片),不会生成任何内容,也不会扣费,HTTP 200 会说明按标价需要多少钱(cost_usd,即模型页面上显示的价格;你支付的是提供商实际收取的费用,可能会不同),以及运行期间会冻结多少(max_cost_usd,即最高计费金额):

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

如果模型的卖家需要某个你未填写的设置(参考生视频模型需要 aspect_ratio),发送时使用的默认值会显示在模型的 schema 中,并在报价中显示为 defaults_applied,例如 "defaults_applied": {"aspect_ratio": "16:9"}。

本会被拒绝的请求也会以同样的方式被拒绝,并给出原因。

锁定价格 15 分钟

POST /v1/quote 接受与图片、视频、音乐或语音请求相同的请求体,并返回标价费用(cost_usd)、运行期间冻结的金额(max_cost_usd,即最高计费金额)以及一个 quote_id(对于转写,发送 model 和 duration_seconds;转写本身不接受 quote_id,用 max_cost 来设置上限):

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

在 15 分钟内用 "quote_id": "6f1c…" 发送相同的请求,就会按提供商实际收取的费用计费,最高不超过 max_cost_usd;如果启动时必须冻结的金额高于 max_cost_usd,就会免费取消。报价本身不扣费,也不冻结金额。

  • 一个报价只能发起一个请求。再次使用它会返回 409 quote_used;从未到达模型的任务会退回该报价。
  • 请求必须要求相同的内容:相同的模型和相同的设置(提示词、尺寸、片段长度、源图片……)。其他任何内容都会被以 400 quote_mismatch 拒绝。max_cost、metadata 和 output_upload_url 可以不同。
  • 15 分钟后,它会返回 400 quote_expired。聊天模型按 token 计费,没有报价:用 provider.max_price 给它们设置上限。

备用模型和价格上限

当第一个模型现在无法提供服务(no_available_provider)或高于你的 provider.max_price 时,"models": ["model-b", "model-c"] 会按顺序指定要尝试的模型。其他任何拒绝都会立即返回。回答的 model 会指明生成它的模型(语音回答本身就是音频文件:活动页面会显示其模型)。带有 quote_id 的请求不接受 models,转写则两者都不接受。

"provider": {"max_price": 0.05} 是一个单位(模型的计价 unit:图片、秒、百万像素、分钟、1K 字符或请求)可能花费的最高金额,单位为美元。高于它的模型会被以 400 max_price_exceeded 拒绝,并且请求的计费绝不会超过其单位数乘以 max_price。其他 provider 选项会被以 400 unsupported_routing_option 拒绝,因为媒体请求的卖家选择不能按请求单独指定。

"model": "best-price:image"(或 image-edit、text-to-video、image-to-video、music、speech、transcription)会为任务选择当前最便宜的可用模型;fastest: 则选择实测最快的模型。参见 模型别名。

标签

"metadata": {"project": "spring-ads"}(最多 16 个文本值)会随任务存储,在任务状态中返回,显示在活动页面和 CSV 导出中,且绝不会发送给模型。对于转写,把它们作为表单字段发送:-F "metadata[project]=spring-ads"。参见 标签。

设置上限

随任何图片、视频、音乐或语音请求发送 "max_cost"(美元,例如 0.50)(转写时作为表单字段)。如果可能花费超过这个数,就会以 400 max_cost_too_low 拒绝,且不扣费。对于视频或音乐任务,确切的上限在任务启动时确定;如果之后结果超过你的 max_cost,任务会免费取消。使用 "validate": true 时,报价会加上 within_max_cost。

重试但不重复扣费

启动视频或音乐任务时,发送一个 Idempotency-Key 请求头(任意唯一字符串,最多 255 个字符,例如 UUID)。如果你的连接断开,并在 24 小时内用相同的 key 再次发送相同的请求,你会拿回同一个任务,而不是第二个任务。相同的 key 搭配不同的请求会被以 409 idempotency_key_reused 拒绝。图片、语音和转写请求不接受 key:失败的那个没有扣费,所以再发一次即可。

您的余额

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 已预留给仍在运行的请求;当这些请求结束时,这笔金额(扣除实际费用后)将退回。available_usd 是新请求可以使用的金额。

每个模型的选项

GET /v1/models?type=image(或 video、music、speech、transcription,两者都包括在内时用 audio,还有 chat、all;多个用逗号连接;没有 type 时,列表只包含聊天模型)会列出你现在可以调用的模型,每个模型都带有它的 type、要发送到的 endpoints 以及它的 pricing。GET /v1/models/<model id> 返回一个模型;对于媒体模型,还会返回一个 parameters 对象:请求体的 JSON Schema,包含它支持的片段长度、分辨率、宽高比和尺寸,以及它需要哪张源图片。

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

pricing 有 usd(当前一次 unit 的最高费用)和 list_usd(模型厂商自己的价格);聊天模型有 input_usd、output_usd 以及它们每 1M tokens 的 list_ 价格。

usd 是现在对模型的普通请求报出的价格:当密钥设置为 Balanced(默认值)时,你的请求会发往的卖家,且已包含我们的费用。这些列表和报价由同一套代码计算得出,并在大约 30 秒内跟随我们卖家的变化(卖家暂停、关闭或重新定价)。

按分辨率定价的模型还有 resolutions:每个分辨率一行(视频的 480p / 720p / 1080p,图片的 1K / 2K / 4K),最便宜的在前,每行都有 usd(该分辨率下一秒或一张图的报价)和 list_usd。上面的 usd 是最便宜的一行。一段视频按它所请求分辨率的单价乘以秒数计费:

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

有些卖家按整段视频定价,而不是按秒。这样的行还会有 seconds:它的 usd 作为每秒价格所对应的片段长度。这是最贵的费率(该模型最短的片段),所以更长片段的费用低于 usd 乘以它的秒数,而未指定长度的请求正好按 usd 乘以 seconds 报价。当某个分辨率只按一种长度出售时,也会出现 seconds。

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

每秒价格会四舍五入到最接近的 $0.000001。要获取某个请求的准确价格,请询价("validate": true)。

错误

HTTP code 含义
400 wrong_endpoint 例如,将图像模型发送到 /v1/video/generations,将聊天模型发送到图像路由,或将语音模型发送到 /v1/audio/transcriptions;消息会指出正确的路径。不收取任何费用,且活动记录中会将其列为已拒绝。
400 invalid_request 请求有误(消息会说明原因,例如模型不支持的时长或缺少源图片)
400 image_required 编辑、图像转视频或参考转视频模型,但没有源图片
400 max_cost_too_low 费用可能超出您的 max_cost;未收取任何费用
400 timestamps_unavailable 向未发送时间信息的转录模型请求 srt、vtt 或 verbose_json;未收取任何费用
409 idempotency_key_reused 该 Idempotency-Key 已用于其他请求
400 quote_mismatch / quote_expired 请求与报价不符,或报价已超过 15 分钟
404 quote_not_found 您的账户中没有此报价
409 quote_used 该报价已启动一个请求
400 max_price_exceeded 该模型每单位成本高于您的 provider.max_price
400 unsupported_routing_option 除 max_price 之外的 provider 选项
404 file_not_found 您的账户中没有此上传文件,或文件已过期
413 file_too_large 上传文件超过 10 MB
429 too_many_files 已保留 500 个上传文件;请删除部分或等待它们过期
503 files_unavailable 目前无法上传文件
413 request_too_large 请求超出大小限制 (40 MB);请将图片作为 https:// 链接发送,并分割长录音
402 insufficient_credits 您的余额不足以支付该任务的最大费用;消息会说明所需金额
404 model_not_found / not_found 您的账户中没有此模型或此任务
404 artifact_expired 文件不再保留(参见上文)
429 rate_limited 请等待 Retry-After 中指定的秒数(如果未指定,则等待几秒),然后重试;X-RateLimit-Remaining 显示本分钟内剩余的请求数量
503 no_available_provider 目前没有卖家可以处理;MartLLM 已尝试其他卖家。消息会列出目前可用的同类型模型