EnglishAPLOVN DEVELOPERS · V1

把视频生成,接入你的工作流。

网页和 API 共用账号积分、价格、任务记录及失败退分逻辑。先上传素材、获取报价,再异步提交和查询任务。

生成请求会实际消耗积分。密钥额度是账号余额内的使用上限,不会额外赠送积分。完整密钥仅在创建时显示一次。

快速开始

  1. 登录网站,进入左侧「API / CLI」,创建密钥并设置额度。
  2. 把密钥放到自己的服务器或环境变量中。
  3. 查询报价,提交时带上报价与固定操作编号。网络重试保持同一编号。
# 基础地址
https://www.aplovn.com/v1

# 所有接口均需要此请求头
Authorization: Bearer YOUR_API_KEY

1. 查询报价

POST /v1/videos/estimate
Content-Type: application/json

{"model":"seedance-2.5","resolution":"480p","duration":5}

# 响应示例(价格以实时响应为准)
{"credits":20,"breakdown":{"output_credits":20,"reference_credits":0,...},...}

活动优惠与报价

/v1/models 和价格表返回基础每秒价;整笔任务的最终活动价以 /v1/videos/estimate 的 credits 为准。有活动时,breakdown 额外包含 base_total_credits、discount_credits 和 promotion(活动名称、支付比例及规则版本)。成片与参考视频费用合计后,只使用一个最优惠活动,总积分向上取整、至少1积分。活动到期恢复基础价,不改变已受理任务的扣费、退款或充值赠送。提交前应重新报价;若返回409,重新获取报价并确认后再提交。已受理任务重试仍使用原操作编号。

活动名额与预算

活动可能设置总减免积分预算、优惠任务总名额和每账号次数。网页与本账号所有API密钥合并计数;报价不预留名额,受理时在扣款事务中核对。名额或预算耗尽时,新报价改用其他适用活动或基础价,不会未经确认按更高价格扣款。已经受理的任务占用优惠额度;失败或取消会退回实际扣款,但不返还活动名额和减免预算。幂等重试不会再次领取。

2. 提交任务

POST /v1/videos
Content-Type: application/json
Idempotency-Key: order-2026-0001

{
  "prompt":"一只橘猫在夕阳下的海边冲浪,电影感镜头",
  "model":"seedance-2.5",
  "resolution":"480p",
  "duration":5,
  "aspect_ratio":"16:9",
  "generation_mode":"t2v",
  "audio":true,
  "enhance":false,
  "expected_credits":20
}

# 响应
{"task":{"id":123,"status":"queued",...},"balance":980}

Idempotency-Key 必填,1–100个无空格的ASCII字符,推荐UUID。同一密钥、同一编号、相同任务参数会返回原任务,不会再次扣费;同一编号改变提示词、模型、素材等参数返回409。报价字段不参与重试身份比较;每个新任务请使用新编号。expected_credits 请使用刚查到的报价;报价变化时返回 409,刷新报价后再确认。

3. 查询和下载

GET /v1/videos/123
GET /v1/videos/123/content

每 5 秒查询一次即可。状态依次为 queued / submitting / submitted / running,结束为 completed / failed。完成后使用带密钥的请求下载 MP4;下载地址不包含密钥或网页登录凭据。

接口列表

方法路径说明
GET/v1/models模型规格、素材能力与基础每秒价格
GET/v1/balance账号可用积分
POST/v1/uploads上传素材,multipart 字段名 file
POST/v1/videos/estimate报价,不生成、不扣积分
POST/v1/videos创建生成任务,实际扣分
GET/v1/videos本人网页及 API 任务;支持 status、q、limit、offset
GET/v1/videos/{id}查询本人任务
GET/v1/videos/{id}/content下载本人已完成任务的 MP4

素材引用

提示词支持 @图片1、@视频1、@音频1、@首帧、@尾帧。数字对应同类 refs 的 position + 1;省略 position 时按该类提交顺序编号。显式 position 从 0 起且同类不可重复,可保留空缺以避免删除素材后旧引用指向其他素材。

系统先校验素材归属和引用编号,再按当前模型能力绑定素材。首尾帧顺序由首帧和尾帧字段固定,不随提示词提及的先后改变。缺失引用或解析后超长会在扣分前拒绝;生成结果对参考的遵循程度仍取决于模型。

10,000 是本站应用上限。实际限制以 GET /v1/models 返回的 specs_by_resolution 为准:按所选清晰度读取 prompt_max、durations、ratios 和 prompt_enhancement。部分通道的提示词上限更低,不会静默截断。网页、CLI 和插件共用服务端校验。模型通道调整只用于新任务,已接收任务保留原归属。

生成参数

参数含义
prompt提示词,本站最多 10,000 字符,不静默截断
modelseedance-2.5 / seedance-2.0 / seedance-2.0-mini / seedance-2.0-fast / wan-3.0
resolution480p / 720p / 1080p,以实时在售规格为准
duration以 specs_by_resolution[resolution].durations 为准;不同清晰度的可选时长可能不同
aspect_ratio如 16:9、9:16、1:1;完整画幅见模型规格
generation_modet2v 文生视频 / omni 全能参考 / frames 首尾帧
audio是否开启音频,默认 true
enhance建议显式传 false;仅 prompt_enhancement=true 的规格可开启
ref_asset_id首帧素材 ID,仅 frames 模式使用
refs参考素材列表,见下方示例
expected_credits本次已确认的积分报价

参考素材

使用 POST /v1/uploads 上传本地文件,响应包含 asset_id / kind / duration_sec。视频时长由服务器检测,提交时无需自行填时长。报价时传 ref_video_asset_ids,以获得多段视频的准确取整报价。

# 全能参考(至少一份素材;可重复多份)
"generation_mode":"omni",
"refs":[
  {"asset_id":"图片ID","kind":"ref_image","position":0},
  {"asset_id":"视频ID","kind":"ref_video","position":0},
  {"asset_id":"音频ID","kind":"ref_audio","position":0}
]

# 首尾帧(首帧必填,尾帧可选)
"generation_mode":"frames",
"ref_asset_id":"首帧图片ID",
"refs":[{"asset_id":"尾帧图片ID","kind":"end_frame","position":0}]

# 视频素材报价
{"model":"seedance-2.5","resolution":"480p","duration":5,
 "ref_video_asset_ids":["视频ID"]}

首尾帧与全能参考分开使用。Seedance 2.0/Mini/Fast 的参考音频需要搭配图片或视频。Seedance 参考视频按合计时长向上取整,最低计 4 秒;Wan 按每段向上取整后相加。Wan 输出与参考视频总时长不能超过 30 秒。具体数量、大小和时长上限见 /v1/models 中的 caps。

素材库与项目

网页左侧「素材库」统一保存本账号上传过的图片、视频和音频;可按项目归类、搜索、改名和批量移动。在生成框选择已有素材,或在任务记录复用原参考素材,无需再次从电脑上传。素材数量、大小、时长及费用仍按所选模型校验。

项目同时整理素材和任务。删除项目将内容移至未分类,不会删除素材、任务或成片。单份素材「从素材库移除」会停止新任务选用,原文件继续保留供已有任务使用;占用空间也包含这些保留文件。当前默认每账号5GB、最多3000份素材,可联系管理员调整。

API密钥可用 GET /v1/projects 查询本账号项目,GET /v1/assets 查询本账号素材,支持 q、kind、project_id、limit、offset。返回的 asset_id 可直接用作生成参考,素材原文件通过 GET /v1/assets/{id}/content 带密钥下载。文件列表不包含内部上游链接。

上传时可用 POST /v1/uploads?project_id=p_... 指定项目;生成请求可增加 project_id,任务列表也支持此过滤。空字符串表示不指定项目;列表查询 project_id=unassigned 表示只看未分类。项目在网页管理;旧客户端不传此字段仍可正常使用。旧上游参考链接会从本站保留的原文件重新准备,不创建额外生成任务。

python aplovn.py projects
python aplovn.py assets --project p_PROJECT_ID --kind ref_image
python aplovn.py upload "E:\素材\角色.png" --project p_PROJECT_ID
python aplovn.py list --project p_PROJECT_ID
python aplovn.py generate --mode omni --image a_ASSET_ID --project p_PROJECT_ID --prompt "让@图片1 的人物向镜头走来" --wait

CLI 使用方法

下载 aplovn.py,使用 Python 3.10 或以上版本。无需安装额外依赖。以下为 Windows PowerShell 示例:

$env:APLOVN_API_KEY="你的API密钥"
python aplovn.py models
python aplovn.py balance
python aplovn.py estimate --duration 5

# 会展示报价并等待确认;--wait 持续查进度
python aplovn.py generate --prompt "海边的橘猫,电影感镜头" --wait

# 上传素材,拿到 asset_id 后用于全能参考
python aplovn.py upload "E:\素材\参考.mp4"
python aplovn.py generate --mode omni --video "asset_id" --prompt "参考视频中的运镜" --wait

# 查询与下载
python aplovn.py status 123
python aplovn.py download 123 --out "E:\视频\123.mp4"

自动脚本确认费用后可加入 --yes。CLI 会自动处理短暂网络重试,并输出本次 request-id;中断后用相同 --request-id 和原参数重试同一任务。不要给同一编号换提示词。

字字动画专用插件

插件入口位于网站左侧独立的「字字动画专用插件」,在「API / CLI」下方。当前版本 0.1.2,查看安装与使用教程。

插件使用用户自己的 Aplovn API Key,与网页共用余额;接入 /v1 接口,不依赖网页登录、浏览器、CLI或号池凭据。网页自动刷新规则不影响公开API。

并发、排队与进度

默认每个账号最多同时执行12条任务,网页、所有API密钥及插件合计计数;超出后仍正常受理并排队,释放位置后自动派发。管理员可在后台任务设置调整执行上限、排队容量和进度显示。密钥单独设置的更小上限仅限制执行,超出的任务同样排队。

任务受理时按原报价预扣积分;派发时不重复扣款,明确失败或取消未开始的排队任务后退回原扣款。默认每账号最多200条等待任务,队列满时返回429并附Retry-After;限流与余额不足仍正常校验。

POST /v1/videos/{task_id}/cancel 可取消尚未派发的任务;已开始处理返回409,重复取消不会重复退款。普通取消在原任务中保留status=failed和error_code=cancelled_before_submit,便于旧客户端继续识别终态。

任务增加 progress_stage 和 progress_display。阶段包括queued、submitting、generating、transferring、checking、completed;没有上游百分比时progress为0,应显示阶段而非计时猜测。生成阶段百分比最高95,成片传输阶段97,完整文件验证保存后100。显示模式stages表示不展示百分比。列表额外返回queued_total、executing_total、concurrency_limit。

接单与异常恢复

报价附带 availability 可用性提示;实际提交会再次检查单号容量,通道仅因繁忙暂不可执行时可排队;无法承接该规格或通道不可连接时在扣分前返回503。可用性不是预约。网络中断会核对原任务,已生成但下载暂不可用会继续取回;超时不直接判定失败退款。上游提交结果不明时可能需要人工核对,不会自动重新生成;音频失败也不会自动改为无声生成。

额度、错误与排障

网站「API / CLI」页可以查看最近调用、调整额度和撤销密钥。网页与 API 的全部任务都在「任务记录」中;密钥仅能使用本账号生成服务,不能访问运营后台或支付管理。