FASTART

开发文档

通过 FASTART 统一 API 调用图片、视频和图片编辑能力，同时保留 MiniMax 格式兼容接口。共用任务队列、素材和 Credit 账本。

FASTART UNIFIED / V1

统一图片、视频与编辑 API

创作台中的已发布模型共用这套接口。只选择模型、生成能力和模式，不选择 Provider。MiniMax 兼容接口保留在下方，两者使用同一企业 API Key 和 Credit 余额。

Base URL
https://api.fastart.ai/enterprise/fastart/v1
GET/enterprise/fastart/v1/models
GET/enterprise/fastart/v1/models/{model}/capabilities
POST/enterprise/fastart/v1/generations/quote
POST/enterprise/fastart/v1/generations
GET/enterprise/fastart/v1/generations/{id}
POST/enterprise/fastart/v1/generations/{id}/cancel

所有调用需要 Authorization: Bearer，无需客户端生成请求 ID。直接提交即可，每次请求创建一个新任务。Idempotency-Key 为可选扩展，仅在需要防重复提交时使用。HTTP 202 表示任务已创建，不代表生成完成。

请求字段说明
model必填。GET /models 返回的 id，不是显示名称。
capability / mode使用目录中的原值；mode 默认 generate。图片编辑工具以 image_viewpoint_edit、image_relight_edit、image_inpaint_edit 标识。
parameters提示词、比例、尺寸、时长、seed 等。只允许当前模型能力公开的参数；不是所有模型都有相同参数。省略使用默认值，seed:null 表示随机。
inputs素材数组，每项 role 加 url 或 asset_id（二选一）。role 使用下方 asset.role；同一角色按数组顺序编号。asset_id 必须属于该 Key 用户及 Workspace。
callback_url可选 HTTPS 回调。建单前向该地址 POST challenge，需原样返回 JSON。收到状态通知返回 2xx；失败最多重试3次，间隔10、30、60秒。
price_token可选。传入报价返回的 price_token，可在价格发生变化时拒绝建单，避免按新价格意外扣费。

素材必须是公网 HTTP(S) 地址，不支持内网、本地路径或 Base64。服务端导入后验证实际类型；参考图片宽高至少240像素，其他数量、尺寸、格式、参考视频时长限制仍由模型配置校验。遮罩须与源图同尺寸；首尾帧角色不能用普通参考图片代替。

cURL · models
curl --fail-with-body "https://api.fastart.ai/enterprise/fastart/v1/models" \
  -H "Authorization: Bearer $FASTART_KEY"
Python · create + poll (requests)
import os, time
import requests

base = "https://api.fastart.ai/enterprise/fastart/v1"
headers = {"Authorization": "Bearer " + os.environ["FASTART_KEY"]}
# Choose model, capability, mode and parameter values from GET /models.
payload = {
    "model": "qwen-image-2-1",
    "capability": "text_to_image",
    "parameters": {"prompt": "A golden retriever on green grass.", "aspect_ratio": "16:9"},
}
response = requests.post(base + "/generations", json=payload,
    headers=headers, timeout=180)
response.raise_for_status()
task_id = response.json()["task"]["id"]
deadline = time.monotonic() + 3600
while time.monotonic() < deadline:
    response = requests.get(base + "/generations/" + task_id, headers=headers, timeout=30)
    if response.status_code == 429 or response.status_code >= 500:
        time.sleep(15)
        continue
    response.raise_for_status()
    task = response.json()["task"]
    print(task["status"], task["progress"])
    if task["status"] == "succeeded":
        print(task["outputs"])  # Signed URLs can be downloaded without a browser cookie.
        break
    if task["status"] in ("failed", "cancelled"):
        raise RuntimeError(task["error"] or task["status"])
    time.sleep(5)
else:
    raise TimeoutError("Keep task_id and query later; do not create another task.")

可用模型与完整参数

以下直接读取当前部署的已发布配置，展开模型查看默认值、枚举、上下限、素材数量及请求示例。后台修改并发布后刷新即可更新；列出模型不表示当前一定有空闲算力或可用定价。

正在读取已发布模型和参数…

报价、状态和结果

报价使用与创建相同的请求体，但不创建任务、不扣费；包含 URL 时会下载并验证素材，随后清理临时副本。报价返回 expected_microcredits、maximum_microcredits 和 price_token。换算比例使用响应中的 microcredits_per_credit。

GET /generations/{id} · response example
{
  "task": {
    "id": "00000000-0000-4000-8000-000000000001",
    "model": "qwen-image-2-1",
    "capability": "text_to_image",
    "mode": "generate",
    "status": "succeeded",
    "progress": 100,
    "outputs": [
      {
        "asset_id": "00000000-0000-4000-8000-000000000002",
        "type": "image",
        "url": "https://assets.example.com/signed/result.png",
        "mime_type": "image/png",
        "metadata": {
          "width": 1328,
          "height": 1328
        }
      }
    ],
    "error": null,
    "billing_status": "settled",
    "usage": {
      "reserved_microcredits": 1000,
      "consumed_microcredits": 1000,
      "released_microcredits": 0
    }
  }
}

每3–5秒查询一次。status 为 queued、running、succeeded、failed、cancelled。无可靠百分比时 progress 为 null；完成为100。outputs 可包含多个图片或视频，URL 有时效，过期后重新查询取得新链接。失败返回统一 error 信息；usage 是 Credit 实际预留、消费和释放记录，关闭计费时可能为 null。

取消是申请，不保证可中断执行中的上游任务；不可取消返回409，不会强行标记失败。任务失败与取消沿用原有退款流程，成本仍保留。所有调用记入 API 账单。同一 Workspace 与 MiniMax API 共享120次/分钟的请求额度，轮询也计入；任务并发仍由会员权益限制。

400 参数或素材错误；401 Key/权限无效；402 余额不足；404 模型或任务不存在；409 价格、幂等或取消冲突；429 限流。未传幂等键时，网络超时或5xx后请先核实任务是否已创建，直接重发可能重复生成和扣费。若主动使用幂等键，重试须保留原键与原请求体。回调暂不带HMAC签名，不跟随重定向，需实现幂等接收；回调结果与查询结构相同，以主动查询为准。

MINIMAX COMPATIBLE / V1
本页描述当前代码实现，不是在线服务状态页。生产域名、Key、路由和定价须先完成配置。

MiniMax · 快速开始

生产 Base URL 如下；本地调试将域名替换为 http://localhost:8001，完整路径不变。URL 不包含语言前缀，也不是 /api/v1。

Base URL
https://api.fastart.ai/enterprise/minimax/v1
  1. 提交并保存 task_id
  2. 轮询状态或接收回调
  3. 下载成功结果

示例在服务器端执行：cURL、Python（先安装 requests）或支持 fetch 与 AbortSignal.timeout 的 Node.js。设置 FASTART_KEY；查询与删除还需将真实 task_id 设置为 FASTART_TASK_ID。

请求示例 · 不会在浏览器中执行
curl --fail-with-body -X POST "https://api.fastart.ai/enterprise/minimax/v1/video_generation" \
  -H "Authorization: Bearer $FASTART_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "A golden retriever running on green grass."
    }
  ],
  "resolution": "352P",
  "duration": 3,
  "ratio": "16:9"
}'

鉴权与 API Key

登录并验证邮箱后提交申请。管理员通过后，用户可在账户中心自行创建多个 API Key，默认脱敏，支持显示完整密钥和复制。网站登录 Cookie 不能替代企业 Key。

Request headers
Authorization: Bearer <FASTART_KEY>
Content-Type: application/json
  • 无需浏览器 Cookie、CSRF 或单独调用登录接口。Key 必须保存在服务端环境变量，不能放在前端代码、URL、日志或 Git 中。
  • Key 关联用户必须已验证邮箱，且仍为 Workspace 的有效可写成员。停用、过期或撤销的 Key 无法调用。
  • 同一 Workspace 内其他有效 Key 可查询任务；跨 Workspace 的查询和删除返回 invalid task_id。

创建视频任务

POST/enterprise/minimax/v1/video_generation

异步创建。HTTP 200 只表示已创建任务，不代表视频已生成。保存 task_id 后使用查询接口。所有场景都必须有且只有一个非空 text 项。

字段类型 / 必填说明
modelstring · required当前实测 MiniMax-H3。校验器也识别 MiniMax-H3-Max，但未配置对应真实路由时不可用。
contentarray · required1–16 项；恰好一个 text，1–7000 字符，不能全为空白。其余为带 role 的素材项。
durationinteger · required3–15 秒整数；具体工作流限制仍生效。不是 4/5 秒起步。
resolutionstring · required352P / 480P / 768P / 1080P / 2K，须使用大写。MiniMax-H3 文生和全模态参考的 1080P / 2K 使用放大工作流；纯文本无需参考素材。首尾帧高分辨率暂未配置。不支持的档位会报错，不自动降级。
ratiostring · conditional21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / adaptive。文生视频必填且不能为 adaptive；参考生成建议明确传入具体比例，详见已知限制。
aigc_watermarkboolean · optional默认 false。true 需要已配置水印参数映射，否则拒绝。
callback_urlstring · optional公网 HTTP(S) 回调地址；先通过 challenge 验证，详见回调章节。
200 · 示例响应 · ID 和 URL 均为占位值
{
  "task_id": "00000000-0000-4000-8000-000000000001"
}

查询任务与结果

GET/enterprise/minimax/v1/query/video_generation/{task_id}

task_id 使用创建返回的 UUID 字符串。只能查询当前 Workspace 最近 7 天内且未删除的企业任务。接口返回状态，不返回百分比进度；建议每 5 秒查询一次。

请求示例 · 不会在浏览器中执行
curl --fail-with-body -X GET "https://api.fastart.ai/enterprise/minimax/v1/query/video_generation/${FASTART_TASK_ID}" \
  -H "Authorization: Bearer $FASTART_KEY"
status含义
queued尚未开始派发，可尝试取消。
running正在派发、执行、收集结果或恢复对账；不可取消，不代表一定在 GPU 上计算。
succeeded成功；读取 content.url 和 usage。
failed失败或超时；读取 error。
cancelled排队期间已取消。
200 · 示例响应 · ID 和 URL 均为占位值
{
  "task": {
    "id": "00000000-0000-4000-8000-000000000001",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1789120000,
    "updated_at": 1789120030,
    "resolution": "352P",
    "duration": 3,
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video",
    "content": {
      "url": "https://assets.example.com/output.mp4?signature=EXAMPLE"
    },
    "usage": {
      "total_seconds": 3,
      "input_seconds": 0,
      "output_seconds": 3,
      "input_image_count": 0
    }
  }
}
返回字段说明
created_at / updated_atUnix 时间戳，单位秒。
content.url仅成功时返回签名下载链接；过期后可在 7 天查询窗口内重新查询。不是永久公开 URL。
usage成功时含 total_seconds = input_seconds + output_seconds、input_image_count；有音频参考时含 input_audio_seconds。秒数按实际素材时长四舍五入；不返回 token 数量。
resolution / duration / ratioresolution 与 duration 表示请求值；最终尺寸和时长以生成文件为准。adaptive 成功时 ratio 为实际宽高的最简比。
task_type / modalitygeneration / video
失败任务示例（HTTP 200）
{
  "task": {
    "id": "00000000-0000-4000-8000-000000000001",
    "model": "MiniMax-H3",
    "status": "failed",
    "created_at": 1789120000,
    "updated_at": 1789120030,
    "resolution": "352P",
    "duration": 3,
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video",
    "error": {
      "code": "1000",
      "message": "video generation failed"
    }
  }
}
Python · 有界轮询
import os
import time
from urllib.parse import quote
import requests

task_id = quote(os.environ["FASTART_TASK_ID"], safe="")
headers = {"Authorization": "Bearer " + os.environ["FASTART_KEY"]}
deadline = time.monotonic() + 1800  # Client wait limit, not a server timeout

while time.monotonic() < deadline:
    response = requests.get(
        f"https://api.fastart.ai/enterprise/minimax/v1/query/video_generation/{task_id}",
        headers=headers, timeout=30,
    )
    if response.status_code == 429 or response.status_code >= 500:
        time.sleep(15)  # Retry this GET only; never resubmit POST
        continue
    response.raise_for_status()
    task = response.json()["task"]
    print(task["status"])
    if task["status"] == "succeeded":
        print(task["content"]["url"])
        break
    if task["status"] in ("failed", "cancelled"):
        raise RuntimeError(task.get("error", task["status"]))
    time.sleep(5)
else:
    raise TimeoutError("Keep task_id and query later; do not resubmit.")

取消或删除任务

DELETE/enterprise/minimax/v1/video_generation/{task_id}

不发送请求体。以服务端当前状态决定行为；查询到 queued 后仍可能已开始执行，此时取消会返回 400。

请求示例 · 不会在浏览器中执行
curl --fail-with-body -X DELETE "https://api.fastart.ai/enterprise/minimax/v1/video_generation/${FASTART_TASK_ID}" \
  -H "Authorization: Bearer $FASTART_KEY"
statusaction结果
queuedcancelled取消任务，释放预占额度。
succeeded / faileddeleted仅隐藏企业 API 记录；不删除资产或账本，不触发退款。
running / cancelled—HTTP 400
200 · 示例响应 · ID 和 URL 均为占位值
{
  "task_id": "00000000-0000-4000-8000-000000000001",
  "action": "cancelled",
  "status": "cancelled"
}

删除后查询或再次删除返回 invalid task_id。失败或结果不确定任务的 Credit 处理由统一账本和恢复机制完成，不能靠重复 DELETE 催退款。

参考图片、视频与音频

素材通过 content 数组传入，不是 multipart 上传。同类素材按数组出现顺序编号，提示词提及顺序不会重排素材。首尾帧与 reference_* 不能混用；图片省略 role 会被当作 first_frame，因此参考图必须明确填写 reference_image。

typerole上限
image_urlreference_image9 张
video_urlreference_video3 段
audio_urlreference_audio3 段
image_urlfirst_frame / last_frame各 1 张；当前有兼容问题
以下 assets.example.com 是占位地址，请替换为无需 Cookie、可从公网访问的真实素材链接。

多参考图示例

请求示例 · 不会在浏览器中执行
curl --fail-with-body -X POST "https://api.fastart.ai/enterprise/minimax/v1/video_generation" \
  -H "Authorization: Bearer $FASTART_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "A golden retriever running on grass. Use the two reference images for its appearance."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://assets.example.com/reference-1.jpg"
      },
      "role": "reference_image"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://assets.example.com/reference-2.jpg"
      },
      "role": "reference_image"
    }
  ],
  "resolution": "352P",
  "duration": 3,
  "ratio": "16:9"
}'

图片＋视频＋音频示例

请求示例 · 不会在浏览器中执行
curl --fail-with-body -X POST "https://api.fastart.ai/enterprise/minimax/v1/video_generation" \
  -H "Authorization: Bearer $FASTART_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "A golden retriever running on grass, guided by the reference motion and audio."
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://assets.example.com/reference.jpg"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://assets.example.com/reference.mp4"
      },
      "role": "reference_video"
    },
    {
      "type": "audio_url",
      "audio_url": {
        "url": "https://assets.example.com/reference.wav"
      },
      "role": "reference_audio"
    }
  ],
  "resolution": "352P",
  "duration": 3,
  "ratio": "16:9"
}'

素材 URL 格式

Media URL examples
https://assets.example.com/reference.jpg
data:image/png;base64,<BASE64_DATA>
data:video/mp4;base64,<BASE64_DATA>
data:audio/wav;base64,<BASE64_DATA>
mm_file://<FASTART_ASSET_UUID>

mm_file:// 仅接受 Key 所属用户及 Workspace 已有的 FASTART 资产 UUID，不接受 MiniMax 的 file_id。本版没有企业 Files 上传接口。外链拒绝内网、回环及云元数据地址；本机文件路径不可直接提交。

素材限制（真实文件检测）
image≤30 MiB；JPG/JPEG、PNG、WEBP、HEIC/HEIF（依赖解码器）；宽高各 256–5760 px，宽/高 0.4–2.5。
video≤50 MiB；MP4/MOV；H.264/H.265，音轨 AAC/MP3；23.976–60 fps；尺寸限制同图片；单段 2–15 秒，同类总计≤15秒。
audio≤15 MiB；WAV/MP3；单段 2–15 秒，同类总计≤15秒。
JSON请求体总计≤64 MiB，包含 Base64 膨胀和 JSON；大文件优先用 URL。用户存储配额和工作流约束也会生效。

状态回调

在创建请求中添加 callback_url，没有单独的回调注册接口。创建前同步 POST challenge，网络超时预算为 1 秒，请立即返回相同 JSON，否则拒绝创建且不扣费。验证计入创建延迟，DNS 解析可能额外耗时。

Challenge request / response
{
  "challenge": "ECHO_THIS_VALUE"
}

状态通知结构与 GET 响应相同。后台每 5 秒扫描状态；不是即时或严格顺序保证。首次投递失败后最多重试 3 次，分别等待 10、30、60 秒（从上次失败起算，总共最多投递 4 次）；扫描和队列可能使实际投递略有延后。接收端按 task.id + status 去重。回调失败不会重新生成；可用 GET 补查。

回调必须公网可达且不能重定向。本版没有回调 HMAC 签名；不要只凭收到的 JSON 修改敏感业务状态，应使用服务端 Key 调用 GET 核实任务。

错误处理与重试

若底层任务已完成但没有视频输出，查询返回 HTTP 200、status=failed、error.code=video_output_missing，回调保持一致。请联系管理员核查，勿据此自动重跑。cancelled 当前不含 error/content/usage，官方对取消态的字段要求仍待确认。

请求失败使用实际 HTTP 错误码和下面的 JSON 信封；任务执行失败则查询仍返回 HTTP 200，task.status=failed。网关拦截（如 413）可能不是此 JSON 格式。

示例响应 · ID 和 URL 均为占位值
{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "media url is required (2013)",
    "http_code": "400"
  },
  "request_id": "00000000000000000000000000000001"
}
HTTP / error.type处理方式
400 · bad_request_error检查参数、素材、路由配置或任务归属；修正后再提交，不原样循环重试。
401 · authorized_error检查 Key、到期时间、邮箱激活和成员权限。
402 · insufficient_balance_error计费启用时额度不足；充值或联系管理员。
429 · rate_limit_error降低查询/提交频率。当前每 Workspace 共享 120 次/分钟，不是 120 路并发；轮询也计入。
500 · server_errorGET 可退避后重查。POST 结果可能不确定，先核实任务记录，保留 request_id 供排查。

请求频率限制

范围上限计数方式
创建、查询、取消/删除任务120 次/分钟同一 Workspace 的所有 Key 和接口共享，轮询也计入。
浏览器申请与密钥管理120 次/分钟按用户共享，独立于生成 API 的限流额度。
管理写请求额外 30 次/小时申请、创建、显示完整 Key、撤销共享；同时受分钟限制。

请求频率不等于任务并发数。并发和排队上限仍按会员等级与队列规则执行；增加 Key 不会增加 Workspace 的请求额度。

生成 API 超限返回 HTTP 429 / rate_limit_error（1002），目前不返回 Retry-After。请降低调用频率，并错开多任务的轮询；管理接口采用浏览器 API 的错误格式。

当前上限固定在代码中，暂不能后台配置。缓存型限流在极端并发下可能略超限，不应视为严格的容量保证。

企业 API 开发文档 · FASTART