模型和路由
MartLLM 将每个请求发送到可用的第三方提供商,以获取您请求的模型。如果提供商在开始响应之前失败,该请求将被重试,并且仍然失败的请求不会收费。每个请求的费用按提供商收取的费用计算,不额外收取 MartLLM 费用,并在 Dashboard → Activity 中列出其成本。您选择模型,而不是提供商。
模型ID
使用目录中的模型ID,例如 deepseek/deepseek-v4-flash、anthropic/claude-sonnet-5 或 z-ai/glm-5.3。列出您现在可以调用的模型:
GET https://api.martllm.com/v1/models:聊天模型,现在可以向其发送请求,因此从该列表填充其模型菜单的工具(SillyTavern, LibreChat, n8n, Cline)只显示它可以聊天的模型。添加?type=video(或image、music、speech、transcription、audio用于这两种类型,chat,多个用逗号连接)用于其他类型,或?type=all用于所有模型,先是聊天,然后是图像、视频、音乐、语音和转录。每个条目都有type(chat、image、video、music、speech、transcription)、endpoints(为其提供服务的路径)和pricing。- 每个聊天模型还会说明它能做什么:
context_length、max_output_tokens、input_modalities(image= 它能读取图片)、supports_tools、supports_reasoning、supports_vision和supported_parameters(它支持的请求字段)。同样的事实也以 OpenRouter 的名称列出(architecture.input_modalities、top_provider.context_length、top_provider.max_completion_tokens,以及每 tokenpricing.prompt/pricing.completion美元),因此为 OpenRouter 列表构建的工具可以直接读取我们的列表。 GET https://api.martllm.com/v1/models/<model id>:一个模型,包含其价格、上下文(聊天),对于媒体模型,还有parameters:请求体的 JSON Schema(参见 制作视频或图像)。- 两个答案中的每个条目还包含:
available:当可以立即处理对其的请求时为true。false意味着目前没有人提供服务,因此请求将被no_available_provider拒绝。请选择其他模型或稍后再试。input_modalities:模型接受的输入。需要图片的模型(图像转视频、参考转视频、图片编辑)会在"text"旁边列出"image";接受视频的模型(超分辨率)会列出"video"。nsfw:对于为成人或未过滤内容(Lustify、“无审查”模型及类似模型)制作的模型,为true。如果您的产品必须保持工作场所安全,请跳过这些模型。
- 公开,无需 API key:
GET https://api.martllm.com/api/v1/public/models(包含价格,以及相同的available、input_modalities和nsfw字段) - 网页:martllm.com/#models,以及每个模型的页面在
martllm.com/models/<model id>
每次请求的流程
- MartLLM 会检查模型是否存在,您的提示是否符合其上下文窗口,以及如果您的请求使用了工具,模型是否支持这些工具。
- 它会从您的余额中预留估算费用,并转发请求。
- 请求会被发送给该模型的一个可用提供商。默认的 Balanced 路由会为每次调用重新选择提供商:最便宜且能为您的提示大小足够快地开始响应的提供商(在测量到的最快速度的 6x 范围内,或在 1 秒内)。该提供商的定价可能高于标价,届时调用费用将按其收费标准计算。当第一个提供商启动缓慢时,一个长的流式提示也会发送给第二个快速提供商,并且在 5 秒后仍未开始的调用可以转移到更快的提供商;您将获得并支付一份回复。您的密钥路由设置(见下文)或请求中的
sort可以更改此行为。工作原理:智能路由。 - 当回复完成时,MartLLM 会根据市场报告的该次调用的价格进行结算,并释放剩余的预留费用。
自动重试
如果调用在任何内容到达您之前失败,MartLLM 会为您重试。 市场会在每次重试时重新匹配卖家,并且对于在路由前失败的调用不收取任何费用,因此重试只会花费您的时间。
- 会重试的情况: 当前没有该模型的卖家 (
no_sellers_for_model,no_healthy_sellers),市场路由超时 (route_deadline_exceeded),请求等待 5 秒或更短时间的429,任何5xx,连接错误,卖家自己的提供商密钥或账户失败,或未及时收到第一个字节。 - 不会重试的情况: 模型不存在,请求无效,或账单/认证问题。这些会立即返回。
- 重试计划: 最多4次尝试,每次尝试之间等待 0.3 秒、0.9 秒,然后 2.7 秒(或者市场发送的
Retry-After,如果它小于或等于 5 秒)。 当没有人销售该模型时,答案会在几秒钟内返回。 - 等待第一个字节: stream 会等待 10 秒(对于长 prompt 或通常较慢的模型会更长);没有
"stream": true的回复会等待 85 秒,因为在完成之前不会有任何内容到达。耗尽全部 85 秒的尝试不会再次等待。在 150 秒后不会开始任何重试。
一旦 streaming 开始,就不会进行任何重试:stream 中途失败会终止 stream,您只需为已生成的内容付费。
如果所有尝试都失败,您将收到错误而不是回复,并且预留会被完全释放。常见的错误有:
| HTTP | code |
何时发生 |
|---|---|---|
| 503 | no_available_provider |
即使重试后,目前也没有人能提供该模型:没有卖家,所有卖家都失败或启动太慢,或者您的 provider 选项没有留下任何可路由的对象。消息会指明模型名称。请稍后重试或选择其他模型。 |
| 503 | service_unavailable |
MartLLM 端出现临时问题。请在几分钟后重试。 |
| 404 | model_not_found |
模型 ID 不可用。 |
请参阅 Errors 获取完整列表。
备用模型
发送 models,并附上一个要尝试的其他模型 ID 列表,按顺序,当第一个模型无法提供服务时:
{ "model": "deepseek/deepseek-v4-flash",
"models": ["z-ai/glm-5.3", "qwen/qwen3.7-plus"],
"messages": [{ "role": "user", "content": "hi" }] }
下一个模型仅在当前没有人能提供前一个模型服务 (no_available_provider),或者在您的 provider.max_price 中没有人销售它时才会被尝试。请求错误(请求体不正确,或任一字段中的模型 ID 未知)以及资金拒绝(余额不足,API 密钥限制)会立即得到响应,并且不会传递到列表中的下一个模型。在 model 和 models 中总共最多 5 个模型。回复的 model 字段和活动行会指明响应的模型。models 适用于 /v1/chat/completions 以及图像、视频、音乐和语音请求;/v1/messages 和 /v1/audio/transcriptions 不读取它。
模型别名
您无需使用模型ID,只需指定您所需的功能,MartLLM便会在每次请求时为您选择合适的模型:
best-price:<job>:可用的模型中,针对一次普通请求价格最低的模型。聊天模型按每百万token的价格(输出按三倍计算)进行比较;图像模型按一张图片(如果按百万像素计价,则为一张 1024×1024 图片)进行比较;视频模型按其最短片段进行比较;音乐模型按一首曲目进行比较;语音模型按 1K 个字符进行比较;转录模型按一分钟进行比较。fastest:<job>:在过去 7 天内,MartLLM上成功请求中位数时间最短的模型(聊天模型为首个token的响应时间,媒体模型为完成文件的响应时间),仅计算至少有 5 次此类请求的模型。如果没有模型满足条件,请求将以503 no_timing_data拒绝,但best-price:仍然有效。
两者都只从当前可用的模型中选择:实时市场显示有健康的卖家,并且MartLLM在过去 10 分钟内对其的最后一次请求没有发现所有卖家都忙碌或宕机(与 /v1/models 上的 available 规则相同)。在媒体路由上,当别名选择的模型回复说最终没有人能处理该请求时,同一请求会转到别名所代表的下一个模型(最多 3 个模型),并且回复中的 model 会指明响应的模型。如果没有可用的模型来完成任务,回复将是 503 no_available_provider,并且不收取任何费用。
<job> 是 chat、image、image-edit、text-to-video、image-to-video、music、speech、transcription 之一。将聊天别名发送到 /v1/chat/completions 或 /v1/messages,将媒体别名发送到其媒体路由。回复中的 model 字段会指明它解析到的模型。GET /v1/models/aliases 列出了当前所有可解析的别名及其对应的模型;GET /v1/models/best-price:chat 描述了它所代表的模型,其中 alias 已设置。
你的 key 的路由设置
每个 API key 都有一个路由设置,位于 仪表盘 → API keys(新建一个 key 或编辑一个):
| 设置 | 作用 |
|---|---|
| 均衡(默认) | 又快又便宜:如上所述,选择启动得足够快的最便宜提供商。定价高于标价的更快提供商也可能响应,这次调用就按它收取的价格计费。 |
| 最低价格 | 始终选择该请求价格最低的提供商。不会选择更快、更贵的提供商,不会让第二个提供商并行竞速,也不会把慢的调用改派给别家。可能会更慢。 |
| 最快 | 最先开始回答的提供商,不管价格多少(等同于 "sort": "latency")。 |
| 收费绝不超过标价 | 开启或关闭,可与以上三种任意搭配。请求只会发送给在请求到达时按等于或低于模型标价出售的提供商,并且计费绝不会高于其 token 按该价格计算出的费用。如果当前没有提供商按该价格出售,请求会以 400 max_price_exceeded 被拒绝,且不产生费用。 |
| 最低折扣 | 0–99%,可与以上任意设置搭配(留空或 0 = 不设最低折扣)。聊天请求只会发送给售价至少比模型官方价格低这么多的提供商,输入和输出分别计算;计费绝不会高于其 token 按官方价格计算后再减去该百分比的价格(与活动页面的“折扣百分比”使用的是同一个官方价格)。如果当前没有提供商这么便宜,请求会以 400 max_price_exceeded 被拒绝,且不产生费用。没有官方价格的模型也会以同样方式被拒绝,因为无法衡量折扣。 |
图片和视频也遵循 key 的设置(自 2026年11月19日 起)。许多图片和视频模型有不止一个卖家,而同一个卖家也可能有不止一种方式生成模型(一种更便宜、更慢,一种更贵、更快)。我们会计时每种方式耗时多久,并统计每种方式失败的频率。卖家市场会和直接卖家排在同一列表中,按它自己的价格和速度排名。
- 默认(
auto,所有没有选择其他设置的 key):生成结果与你要求完全一致的最便宜卖家。它只会跳过持续失败的卖家,或耗时超过我们测到的最快卖家两倍的卖家。因此,从未改过设置的 key 不会为了小幅提速而多付钱。 - 均衡(
balanced):最多比我们测到的最快卖家慢 20% 的最便宜卖家。尚未测速的卖家也算足够快。当你愿意为更快的结果多付钱时,选这个。 - 最低价格(
cheapest):始终是生成结果与你要求完全一致的最便宜卖家,无论多慢。 - 最快(
fastest):我们测到的最快卖家。它可能比最便宜的卖家贵,但绝不会高于你的请求对应的模型标价。
一个卖家在过去 7 天内为该模型完成至少 3 个任务后,才会参与测速;在没有任何卖家被计时之前,所有设置都会选择最便宜的卖家。在最近 10 个任务中完成少于 7(尝试 10 次或更多)的卖家,在所有设置下都会排在健康卖家之后;我们比较的时间是任务预计需要的时间:每五个任务丢一个的卖家,会被计为慢 25%。报价中的价格("validate": true)和任务的 estimated_cost_usd 都是你的 key 设置所选卖家的价格;当卖家按标价收费时,任务就按这个价格计费。如果该卖家无法接这个任务,就按同一顺序由下一个卖家接手。
请求本身没有指定时,会应用该设置。请求自带的 provider.sort、:floor / :nitro 或 provider.max_price 会覆盖它。provider.only: ["uberllm"] 不是排序,所以 key 的设置仍然生效。最低折扣是例外:它始终生效,并且与请求自带的 provider.max_price 一起时,以更严格的价格为准。
通过仪表盘 API:在 POST /api/v1/keys 和 PATCH /api/v1/keys/{id} 上的 routing(auto、balanced、cheapest 或 fastest;对于文本,balanced 等同于 auto)以及 price_cap_listed(true/false)和 min_discount_pct(整数 0–99);这些都会由 GET /api/v1/keys 返回。
路由选项
provider 对象在 /v1/chat/completions 上读取。MartLLM 无法应用的选项会以 400 unsupported_routing_option 拒绝,且不收取任何费用,因此请求绝不会在设置被静默丢弃的情况下运行。
| 选项 | 作用 |
|---|---|
only / allow |
仅限这些路由或提供商。uberllm(MartLLM 的 marketplace 路由)和 seller(卖方自己的报价)在我们自己的路由之间进行选择。任何其他名称,例如 openai 或 api.venice.ai,都是 marketplace 上的提供商:请求随后通过 uberllm 路由,该路由仅使用这些提供商的报价。 |
ignore / deny |
绝不使用这些。路由名称如上所述。提供商名称(最多 32 个)在 marketplace 上被拒绝,请求随后通过 uberllm 路由。 |
order |
首选顺序。路由名称对我们的路由进行排序;提供商名称设置 marketplace 的尝试顺序。它绝不会使提供商符合或不符合资格。 |
sort |
price(默认)、latency(在价格区间内,优先选择观察到的最快者)或 uptime(在同一区间内,优先选择最可靠者)。throughput 仅对我们自己的路由进行排序。 |
max_price |
您每百万 token 支付的最高费用,以美元计:{ "prompt": 1.0, "completion": 3.0 }。价格高于此的路由将被跳过;marketplace 路由对卖方的限制是,其价格至少要比模型的标价低到您的上限所需的程度。如果没有任何剩余,请求将以 400 max_price_exceeded 拒绝,且不收取任何费用。当您同时设置 prompt 和 completion 时,请求所使用的 token 绝不会超出这些限制计费。 |
allow_fallbacks |
false 关闭上述自动重试;第一次失败将返回给您。 |
data_collection |
仅接受 "allow"(默认)。 |
zdr, require_parameters |
仅接受 false。 |
:floor 和 :nitro 模型后缀被接受并从 model id 中剥离;:floor 按价格排序,:nitro 按吞吐量排序。
对于图像、视频、音乐和语音,每个请求都会发送给该模型的可用第三方提供商。provider.max_price 是一个单位(图像、秒、百万像素、分钟、1K 字符或请求)可能花费的最高金额,以数字表示:{ "max_price": 0.05 };它也限制了账单。所有其他 provider 选项均不适用于媒体。
标签
在任何请求中发送 metadata,它是一个最多包含 16 个文本值的对象(键最多 64 个字符,不含冒号;值最多 512 个字符):
{ "model": "deepseek/deepseek-v4-flash", "messages": [...],
"metadata": { "project": "spring-ads", "run": "42" } }
标签与请求一同存储,绝不会发送给提供商。它们会显示在 Dashboard → Activity 中的请求上、视频或音乐任务的状态中,以及 CSV 导出文件(metadata 列)中。使用 GET /api/v1/usage/activity?tag=project:spring-ads 按标签筛选 Activity(重复 tag 可要求多个);CSV 链接会应用相同的筛选条件。在 /v1/messages 上,Anthropic 自己的 metadata ({"user_id": "…"}) 也以同样的方式存储。