AIFooler API 接入文档

快速开始

先登录并创建 Key，将它保存为服务端环境变量。按上传 → 提交 → 查询 → 下载四步调用。以下查询步骤只执行一次，任务未完成时由你的业务定时再次查询；成功后再执行下载。

import os, requests

base = "https://www.aifooler.com/api/v1"
headers = {"Authorization": "Bearer " + os.environ["AIFOOLER_API_KEY"]}

# 1. 上传文件
with open("song.wav", "rb") as audio:
    response = requests.post(base + "/uploads", headers=headers, files={"file": audio})
response.raise_for_status()
file = response.json()

# 2. 提交分离任务
response = requests.post(base + "/jobs/separate",
    headers=headers,
    json={"file_id": file["id"], "profile_id": "vocal_background"})
response.raise_for_status()
job = response.json()
print(job["id"])

# 3. 稍后查询任务；未完成时，每隔 3–5 秒再次查询此接口
response = requests.get(base + "/jobs/" + job["id"], headers=headers)
response.raise_for_status()
result = response.json()
print(result["status"])

# 4. 任务成功后，使用返回的地址下载音轨
if result["status"] == "succeeded":
    for track in result["artifacts"]:
        response = requests.get("https://www.aifooler.com" + track["download_url"], headers=headers)
        response.raise_for_status()
        with open(track["name"] + ".audio", "wb") as output:
            output.write(response.content)

认证与密钥

Authorization: Bearer afk_…

每个账户最多 5 个有效 Key；完整 Key 只在创建时展示一次，删除后新请求立即失效。每个文件、任务和下载都校验账户归属。Key 不可以替代网站登录态，也不能用于会员管理或支付接口。

接口参考

账户与处理预设

查询可用时长，选择人声分离的处理方式。

返回 available_seconds、reserved_seconds、used_seconds、total_seconds、membership_active 和 key_id。所有时长以秒为单位。

读取公开预设，使用返回的 id 作为 profile_id。完整取值、用途及输出音轨见下方模型参数表。

上传音频

multipart/form-data 上传 file。成功返回 201：id、file_name、duration_seconds 和 size_bytes。上传不扣处理时长，但需要有效会员和正余额。本站不额外设置上传有效期，上游文件须仍可读取。

提交分离任务

JSON：file_id、profile_id；可选提供 8–128 个可见 ASCII 字符的 Idempotency-Key，防止重试重复创建；不提供时每次请求创建新任务。返回 200 及任务 id（仅表示受理成功，处理仍为异步，请继续查询任务状态）。相同账户、相同幂等键和参数返回原任务；不同参数返回 409。使用幂等键的请求，重试时复用原键。

任务历史

返回本账户最近 50 条 API 任务。

查询任务结果

使用提交任务返回的 id 查询。详情返回状态、输入时长、计费秒数和结算状态。成功时包含 artifacts，每个产物提供 name、display_label、站点根相对 download_url。不要将下载路径再次拼接到 /api/v1 后。

下载分离音轨

任务成功后，直接请求详情中每条音轨的 download_url，无需自行拼接路径。这一步用于取得人声和伴奏文件。

携带同一账户的有效 API Key 下载，支持单段 Range。本站转发文件，不向调用者返回上游地址。每次下载都会检查有效会员资格；会员过期无法下载。本站不额外设置结果有效期，上游文件失效时返回下载错误。

创建任务参数

以下为完整可配置字段。模型通过 profile_id 选择，不直接传网站内部的 model 编号。两个字段都必填且没有默认值；额外字段会返回 400。当前不接受自定义 stem、输出格式、采样率或客户端申报的时长，时长由服务器解析。

模型与处理预设

与人声分离页共享模型配置；每个预设自动设置对应处理模型和输出音轨。所有预设均按输入音频时长计费，切换模型需要创建新任务并使用新的幂等键。

{"file_id":"上传返回的 UUID","profile_id":"harmony"}

例如使用 harmony 提取和声，使用 vocal_background 分离人声与伴奏，使用 dereverb 去混响。GET /operation-presets 返回 data 数组，每项包含 id、name、description、billing 和 outputs（name、display_label），以接口实际返回的列表为准。

状态与结算

HTTP 200 表示创建请求已成功受理，不代表处理完成。queued → submitting → processing → succeeded / failed。创建请求超时或受理结果不明确时为 uncertain，保留额度等待核对；查询无法消除不确定性时请联系支持，不要更换幂等键重复提交。billing_state 为 reserved、charged 或 released。

计费与共享余额

• 计费沿用网页规则，将服务器解析的音频时长向下取整为整数秒（Math.floor）。例如 200.9 秒计为 200 秒，不足 1 秒计为 0 秒，多个输出音轨只计一次。
• 提交前原子预留，处理成功结算，明确失败释放；查询和下载不重复扣处理时长。
• 网页版和 API 使用同一账户时长余额，不能消费网页免费次数。
• 创建 Key、上传、提交任务、查询和下载需要有效会员。会员过期后 Key 不删除，但调用被拒绝；已受理任务继续处理并结算。
• 已受理任务不受 Key 后续删除影响，仍会处理并结算。当前不开放取消接口。

限制与错误

所有调用统一使用 Authorization: Bearer API Key，无需打开网页或保持网页登录。

• 账户必须为有效会员（未到期或终身会员），每个账户最多 5 个有效 Key；删除后的 Key 立即不能调用。
• 文件、任务、历史和下载按账户隔离，只能访问本账户资源。
• 上传时需有可用处理时长；提交时可用余额须足够支付整个音频，否则返回 402。查询和下载不额外扣费，余额耗尽仍可查询和下载已完成任务。
• 本站不设置调用频率、并发、任务数量、文件大小和音频时长上限。文件须非空且能被上游解析为音频，实际上游及部署网关能力仍决定文件是否可处理；本站不承诺无限文件大小。
• 上传仅接受一个 file 字段；提交 JSON 仅接受必填的 file_id、profile_id。预设须来自下表，时长由服务器解析，不能由调用方指定。
• 幂等键可选；填写时需为 8–128 个不含空格的可见 ASCII 字符，相同键不能用于不同参数。
• 本站不额外设置上传和结果的过期时间；上游文件失效后将无法处理或下载。
• Key 名称为 1–80 个字符。JSON 请求体最多 8 KiB；上游普通接口请求超时 60 秒，准备上传 30 秒、上传 120 秒，下载连接超时 30 秒。下载支持单段 Range。任务历史接口返回最近 50 条，控制台显示最近 20 条调用。

{"error":{"code":"insufficient_minutes","message":"账户可用时长不足，请充值或等待其他任务结束"}}