快速开始
一个密钥，一种请求格式，适用于所有图像和视频模型。提交任务，轮询状态，获取文件。
/data/models.json。POST /v1/chat/completions 调用，按 token 从同一份额度中计费：见 chat completions。| Base URL | https://api.revana.si/v1 |
| 认证 | Authorization: Bearer <key> |
| 提交 | POST /v1/generations |
| 轮询 | GET /v1/generations/{id} |
| 模型 | GET /v1/models （无需密钥）：当前所有可用于生成的模型 |
| 余额 | GET /v1/balance：你的密钥所属账户可花费的金额 |
| 上传 | POST /v1/uploads：为你电脑上的参考文件生成的链接 |
| 格式 | JSON 输入，JSON 输出。价格以美元计；100 额度 = $1。 |
| 机器可读 | /openapi.json · /llms.txt |
认证
在你的账户中创建密钥，然后在每个请求中将它作为 bearer token 发送。请把它保存在你的服务器上，切勿放进浏览器或移动应用中。
提交生成任务
发送模型 id 及其 input。响应会立即返回，包含生成任务的 id 和状态 queued；实际工作在后台进行。
| 字段 | 类型 | 说明 |
|---|---|---|
model | string，必填 | 模型页面上的模型 id，例如 seedance-2.5。 |
input | object，必填 | 提示词和设置；见输入字段。未知字段会被拒绝。 |
max_cost_usd | number，可选 | 你愿意为这次生成支付的上限，最高为 100（默认值）。价格高于它的线路会被跳过；如果一条都不剩，请求会返回 422 max_cost_exceeded。 |
max_wait_s | integer，可选 | 预计耗时超过这个秒数的线路会被跳过。超过该时间后不再尝试新线路，但已经在运行的线路允许继续完成（最长 40 分钟），如果它成功交付则会扣费。 |
Idempotency-Key | header，可选 | 最多 200 个字符。重新发送同一个 key 和相同的请求体（超时或收到 503 之后），你拿到的是同一个生成任务，而不是第二个。同一个 key 搭配不同的请求体会返回 409 idempotency_conflict。 |
获取结果
想要按模型划分的接口和完成回调 webhook？请参阅兼容 fal 的队列 API，了解请求 ID、状态/结果 URL、支持的 fal 别名以及迁移限制。
每隔几秒轮询一次，直到 status 变为 succeeded 或 failed，然后用你的密钥下载 output.urls 中的文件：第一个用 GET /v1/generations/{id}/content，图片模型返回多张时依次是 /content/2、/content/3……。图片通常几秒内完成；视频则根据模型和时长，需要不到一分钟到几分钟不等。
一个已完成的生成任务：
输入字段
各模型使用相同的字段名。每个模型接受哪些字段和取值及其默认值，在 /data/models.json（options、tasks）中按模型列出。如果模型不支持某个字段或取值，请求会在扣费之前以 422 invalid_input 被拒绝。
| 字段 | 类型 | 用途 |
|---|---|---|
prompt | string | 要生成的内容。文生图和文生视频必填。 |
image_url | string (URL) | 图生视频的起始帧，或图生图要编辑的图片。 |
end_image_url | string (URL) | 尾帧，适用于支持首帧加尾帧的模型。 |
image_urls | string[] | 参考图，数量不超过模型的上限。 |
resolution | string | 720p、1080p、2K……模型支持的分辨率之一。 |
duration | number | 视频时长（秒），为模型支持的时长之一。 |
aspect_ratio | string | 16:9, 9:16, 1:1... |
audio | boolean | 在模型支持的情况下，随视频生成声音。可能会改变价格。 |
negative_prompt | string | 要避免的内容，适用于支持该参数的模型。 |
video_url | string (URL) | 要转换、延长或放大的片段。系统会测量其时长，按秒计费的模型会据此计费。 |
audio_url | string (URL) | 说话头像或口型同步模型据以生成动画的人声或声音。 |
quality | string | 按质量档位定价的模型使用的质量档位（例如 low、medium、high）。 |
seed | integer | 随机种子，适用于支持该参数的模型。 |
Seedance 2.5 默认为 720p、5 秒（4–30）、16:9 且无声音，同时还接受：
| 字段 | 类型 | 用途 |
|---|---|---|
video_url | string (URL) | 要编辑的 4–30 秒片段。结果保持原有时长，因此请省略 duration。 |
video_urls | string[] | 参考片段，最多 10 个，总计最长 30 秒。其秒数按视频输入费率计费。 |
audio_urls | string[] | 参考声音，最多 10 个，总计最长 30 秒。 |
image_url 是精确的首帧，因此不能与参考素材同时使用；如需较宽松的视觉参考，请使用 image_urls。end_image_url 需要 image_url。素材必须是可直接下载的公开 https URL。
Nemesis
nemesis 用你自己的人物、产品和场景重新演绎一段片段：保留片段的运动、节奏和镜头，由最多 8 张参考图来“出演”。结果保持片段原有的时长和画幅。价格为 Seedance 2.5 编辑费率加每秒 $0.02（480p、720p 和 1080p 分别为 $0.08、$0.17 和 $0.36），按输入片段的每秒加上输出视频计算。
它遵循 Scenario ALTER 的方案：编辑的是你的片段本身，无声，并把其中一帧按已完成修改的样子重绘，作为第一张参考图，之后再把片段原有的声音加回去。如果有多个人物，图片会按人物在首帧中从左到右的站位依次匹配。
| 字段 | 类型 | 用途 |
|---|---|---|
video_url | string (URL)，必填 | 要重新演绎的 4–30 秒片段。 |
image_urls | string[]，必填 | 1–8 张参考图。 |
roles | string[] | 每张图一个：person（默认）、product、location 或 look。 |
target_frame | boolean | 渲染之前，片段的首帧会按已完成修改的样子，以相同的姿势、尺寸和光线重绘，并作为第一张参考图发送，这样发型、面部和衣着都能忠实于你的图片。nemesis 默认开启，nemesis-lite 默认关闭。免费。 |
guide | string | nemesis-lite 仅限（nemesis 始终编辑片段本身）。clip（有目标帧时的默认值）：遵循片段自身的画面。people（没有目标帧时的默认值）：替换人物并保留背景。scene：所见的一切都来自参考图和提示词。 |
sound | string | original （nemesis 上默认开启）：把片段原有的声音加回去。none（nemesis-lite 上默认）：无声。 |
face_mesh | boolean | nemesis-lite 仅限。追踪片段中的每一张脸，让新面孔保留其表情、眼神和嘴型。使用 guide: "people" 时默认开启，scene 和 clip 默认关闭。发送 false 可保持关闭。结果中不会显示。 |
resolution | string | 480p、720p（默认）或 1080p。 |
prompt | string | 可选的指示，最多 5000 个字符。 |
在 nemesis-lite 上，如果片段中没有人物，并且以 guide: "people" 发送，会以 invalid_input 被拒绝且不扣费；请改用 scene 或 clip 发送。
需要多长时间。首先准备片段：在 nemesis 上会绘制目标帧，约 15–40 秒；在 nemesis-lite 上会分离人声并把每一帧变成深度引导，8 秒的片段约 25 秒，30 秒的片段约一分半。然后渲染视频，这是等待时间的大头：8 秒、480p 的片段约需 4–7 分钟。请轮询该生成任务直到完成。
Nemesis Lite
nemesis-lite 接受与 nemesis 相同的输入，并在 Wan 3.0 上渲染：更便宜，在面部和细节上略逊一些。片段为 2–15 秒。价格为 Wan 3.0 的费率加每秒 $0.02（480p、720p 和 1080p 分别为 $0.07、$0.11 和 $0.19），按输入片段的每秒加上输出视频计算。
生成任务对象
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 生成任务 id（gen_…），用于轮询。 |
object | string | 始终为 generation。 |
model | string | 你请求的模型。 |
status | string | 见状态。 |
message | string | 仅在正与供应商确认结果期间出现：当前正在发生什么。 |
quoted_usd | number | 最便宜线路上的价格，也就是最先尝试的线路。如果它无法完成而由更贵的备用线路完成，则按该线路的价格扣费，最高不超过 reserved_usd。 |
reserved_usd | number | 从你的余额中预留的金额：如果在尝试其他线路之后由更贵的备用线路完成，这是该任务最高可能的费用。结算时多出的部分会被释放。若想保证支付不超过 quoted_usd，请把 max_cost_usd 设为该值：更贵的备用线路随后会被跳过。 |
output | object | null | 成功时：urls，即结果文件（图片模型可能返回多个），包含 width 和 height；视频还有 duration_s 和 has_audio。请及时下载；文件会过期。 |
cost_usd | number | null | 实际扣费金额。生成任务成功后设置；失败时为 0。 |
attempts | number | 已尝试的线路，包括回退。只有成功的那条会计费。 |
error | object | null | 失败时：code、message 和 retryable；内容被拒绝时还会有 reason。见生成任务失败的原因。 |
created_at, completed_at | string | ISO 8601 时间戳。 |
状态
| 状态码 | 含义 |
|---|---|
queued | 已接收，等待分配线路。 |
running | 生成中。如果某条线路失败，任务会在转到下一条线路期间保持为 running，在确认结果期间也是如此（见 message）。 |
succeeded | 完成。output.urls 包含文件，cost_usd 为你支付的金额。 |
failed | 所有线路都失败，或输入被拒绝。不扣费。 |
计费
- 你用预付额度付费，每 1 美元兑换 100 额度，可购买 $10 到 $5,000 的额度包。每个价格都是整数额度。
- 提交时，
reserved_usd会从你的余额中预留。如果生成失败，全部预留都会释放。 - 只有生成成功时才会扣费，按完成它的那条线路的报价计算。通常是首选线路的
quoted_usd。如果必须由备用线路完成，可能会更贵：按该线路的价格，或者，如果之前尝试的某条线路被其供应方计费，则按那些尝试的成本加 10%，取较高者。绝不会高于reserved_usd。 - 没有月度配额，也没有每分钟上限：你的余额和
max_cost_usd就是限制。 - 每个模型的价格在其页面和价格表中。
余额
你的密钥所属的账户。在大批量任务之前先查一下；它不产生费用，也不计入生成任务的限额。
| 字段 | 含义 |
|---|---|
available_usd | 新的生成任务可以预留的金额。提交时如果 reserved_usd 超过它，将返回 402 insufficient_credits。 |
held_usd | 由仍在运行的生成任务预留的金额。它们没用完的部分会在结算时退回。 |
balance_usd | 可用余额加上预留金额。 |
spent_usd | 已完成的生成任务的累计扣费。 |
*_credits | 以额度表示的同样金额（每美元 100 额度），已做取整，确保可用余额不会显示得比实际更高。 |
上传参考文件
参考素材以公开的 https:// 链接传入。对于你本机上的文件，请先申请上传链接，把文件内容发送到那里，再使用返回的链接。此操作免费。
| 字段 | 含义 |
|---|---|
upload_url | 请在一小时内用 PUT 把文件发送到这里，并且请求头必须与 upload_headers（其类型和大小）完全一致。其他任何内容都会被拒绝。 |
url | 文件在 api.revana.si 上的链接，有效期至 expires_at（14 天）。它不需要密钥，会重定向到文件，因此任何能获取链接的程序都可以读取它。可在 POST /v1/generations 中把它用作参考素材。文件会在不久后被删除。 |
id | upl_… |
图片（image/*）最大 30 MB，视频片段（video/*）最大 50 MB，声音（audio/*）最大 15 MB。更大的文件或其他类型的文件会返回 413 too_large 或 400 invalid_request。
生成任务失败的原因
failed 的生成任务带有 error.code、一条写给请求者看的 message，以及 retryable：稍后重新发送同一个请求可能成功时为 true，请求本身必须修改时为 false。失败的生成任务不会扣费。
| 错误码 | 可重试 | 何时 |
|---|---|---|
content_policy | no | 模型拒绝了提示词或素材，或者扣留了已生成的内容。reason 说明触发的规则：sexual（NSFW 或成人内容）、minors（儿童或青少年）、copyright（受版权保护或第三方的素材、品牌、角色）、real_person（真实人物或名人的肖像），或者模型没有给出原因时为 other。 |
invalid_input | no | 某个参考素材无法读取，只发送了一张图片但提示词提到了 @Image2，或者某个值被模型拒绝。错误信息会说明具体是哪种情况。 |
model_declined | no | 模型用文字作答，而没有生成图片或视频，通常是因为提示词要求了它所需但并未发送的内容。请让提示词直接描述结果本身。 |
reference_changed | no | 某个参考文件在校验之后发生了变化。请重新发送。 |
max_cost_exceeded | no | 唯一可运行的线路费用高于 max_cost_usd。 |
model_busy | yes | 该模型的所有线路都已满载。请一分钟后重试。 |
model_unavailable | yes | 目前该模型没有任何线路可以接受这个任务。 |
timeout | yes | 没有线路在规定时间内返回结果，或者 max_wait_s 已过。 |
all_routes_failed | yes | 所有线路都因它们自身的原因失败。 |
错误
错误使用 HTTP 状态码和 JSON 响应体：{"error": {"code": "...", "message": "..."}}。
| HTTP | 错误码 | 何时 |
|---|---|---|
| 400 | invalid_request | 请求体不是 JSON，缺少 model 或 input，或者包含 API 无法识别的字段。 |
| 401 | unauthorized | API 密钥缺失或无效。 |
| 402 | insufficient_credits | 你的可用余额不足以支付 reserved_usd。请充值后重试。 |
| 403 | account_disabled | 账户已被暂停。请联系支持团队。 |
| 403 | generation_not_enabled | 你的密钥目前只能查询价格，还不能生成。 |
| 404 | not_found | 你的账户下没有该 id 对应的生成任务。 |
| 409 | idempotency_conflict | 这个 Idempotency-Key 已经配合另一个不同的请求体使用过。 |
| 409 | not_ready | 在生成任务成功之前就请求了文件。 |
| 413 | body_too_large | 请求体超过 1 MB。请以 URL 的形式发送素材。 |
| 422 | invalid_input | 模型不支持的字段、取值或组合，或者素材无法读取。不扣费。 |
| 422 | max_cost_exceeded | 所有线路的费用都高于 max_cost_usd。 |
| 422 | model_not_available | API 上没有该 id 对应的模型。各模型 id 见模型页面。 |
| 429 | rate_limited | 同一账户在同一秒内发出的请求过多（用于防止失控的循环，不是配额）。请等待 Retry-After 秒。 |
| 429 | concurrency_limit | 账户进行中的生成任务数已达上限。请在其中一个完成后重试。 |
| 503 | busy | 暂时负载较高。请在 Retry-After 之后使用同一个 Idempotency-Key 重试。 |
| 503 | model_unavailable | 该模型目前没有任何线路可用。请稍后重试。 |
| 500 | server_error | 我们这边出了问题。使用同一个 Idempotency-Key 重试是安全的。 |
模型列表
所有模型及其选项和价格都以 JSON 形式发布在 /data/models.json，本站正是根据这个文件渲染的。