图像、视频、音乐和语音
您用于文本的 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 已尝试其他卖家。消息会列出目前可用的同类型模型 |