Media Studio API 文档0.21.8.47 · 视频 / 图片 / B 渠道文档已更新
MEDIA STUDIO DEVELOPER PLATFORM

统一调用视频与图片能力

第三方只对接 Media Studio,不需要了解 H / C / A / S / M / K / Z / Y / B / T 的上游私有协议。模型名称、参数、计费、任务状态和结果地址都由 Media Studio 统一输出。

鉴权与 Base URL

所有第三方请求使用用户在“API 接入”中创建的 sk-ms-... Key。

Base URL

https://api.haohaoma88.top

Authorization

Authorization: Bearer sk-ms-xxxxxxxxxxxxxxxx
Content-Type: application/json
API Key 与网页账号共用余额、渠道可见性、模型定价和扣费规则。不要把 Key 写进浏览器公开代码、仓库或日志。

统一模型发现

推荐先调用 GET /v1/models。返回列表包含开放的视频模型、图片 B 模型,以及已核实分辨率成本且开放的图片 A 模型。图片 A 在统一接口中使用 IMAGE_A 渠道和公开模型 ID,不公开原始 T 账号或上游模型标识。

GET
/v1/models统一模型列表。通过 type 区分 video / image。
GET
/v1/videos/channels读取当前账号可见的开放视频渠道;id/code 是稳定路由代码,name 是管理员可修改的用户端显示名称。
GET
/v1/videos/models?channel=Z读取指定渠道的模型完整参数、workflow 和参考素材能力。
GET
/v1/videos/models/{model_id}读取单个视频模型详情。
{
  "object": "list",
  "count": 2,
  "data": [
    {"id":"...","type":"video","name":"...","channel":"Z","workflow":"video_generation","available":true},
    {"id":"gpt-image-2","type":"image","name":"gpt-image-2","channel":"IMAGE","resolutions":["1K","2K","4K"]}
  ]
}

视频生成

先读取模型能力,再上传素材、估价、创建异步任务。模型的时长和分辨率不要写死在客户端。

POST
/v1/videos/cost按当前 model + duration + resolution + aspect_ratio + medias 估算积分。
POST
/v1/videos/generations创建一条视频任务。建议携带唯一 Idempotency-Key。
curl -X POST 'https://api.haohaoma88.top/v1/videos/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: order-000001' \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"MODEL_ID_FROM_/v1/videos/models",
    "prompt":"人物在古城街道向前行走 @图1",
    "duration":15,
    "resolution":"720p",
    "aspect_ratio":"16:9",
    "medias":[
      {"media_id":"ccm_xxx","value":"ccm_xxx","type":"image","role":"image_references"}
    ]
  }'
不要根据显示名称推断能力:M / K / Z / Y / B 模型可以由管理员改显示名称;时长、分辨率、素材数量、billing_unit 和 workflow 应以模型接口当前返回为准。B 渠道尤其不要从名称中的“按条/按秒”文字自行推断计费单位。

素材上传

视频生成前可把本地图片、音频或视频上传给 Media Studio。接口同时兼容二进制直传和常见的 multipart/form-data,第三方程序任选其一即可。

POST
/v1/videos/media/upload返回的 media_id / value 可直接放进生成请求 medias。
# 方式一:multipart/form-data(第三方程序推荐)
curl -X POST 'https://api.haohaoma88.top/v1/videos/media/upload' \
  -H 'Authorization: Bearer sk-ms-完整Key' \
  -F 'channel=Z' \
  -F 'media_type=image' \
  -F 'role=image_references' \
  -F 'file=@./ref.png'

# 方式二:原始文件二进制(继续兼容)
curl -X POST 'https://api.haohaoma88.top/v1/videos/media/upload?channel=Z&filename=ref.png&media_type=image&role=image_references' \
  -H 'Authorization: Bearer sk-ms-完整Key' \
  -H 'Content-Type: image/png' \
  --data-binary '@./ref.png'
media_type常用 role说明
imageimage_references / start_image / end_image参考图或首尾帧
videovideo_references / input_video参考视频或视频超分源视频
audioaudio_references / input_audio参考音频
multipart 文件字段支持 file、media、image、video、audio 以及常见编号字段。multipart 模式下 filename 会自动取上传文件名;不要手工设置不带 boundary 的 Content-Type: multipart/form-data,应让 HTTP 客户端自动生成 boundary。原始二进制模式才要求在 query 中提供 filename 和 media_type。不同模型允许的素材类型和数量不同,仍应优先读取模型返回的 medias 与 reference_limits。B 渠道的 3 个 DSN 型号使用 Media Studio 临时 HTTPS relay:本地素材上传后由服务端转换为上游 assets=[{kind,url}],每个型号最多 9 张图片、3 个视频、3 个音频,总计 15 个。

视频超分

视频超分模型也通过统一视频接口调用。模型列表中 workflow=video_upscale 表示它属于视频处理,而不是普通提示词生成。

GET
/v1/videos/models?channel=K寻找 workflow=video_upscale 的开放模型。
POST
/v1/videos/media/upload?...media_type=video&role=input_video上传 1 个源视频。
POST
/v1/videos/generations提交模型要求的目标 resolution / duration,并在 medias 中传入源视频。
当前 K 超分模型要求恰好 1 个参考视频。目标分辨率仍以模型接口返回为准。

任务状态与下载

视频任务为异步任务。建议每 5 秒左右查询一次;不要高频轮询。

GET
/v1/videos/{task_id}返回统一任务状态和 progress(0–100)。
GET
/v1/videos/{task_id}/download任务完成后通过 Media Studio 下载成片。
状态含义客户端处理
queued / submitting本地排队或正在提交上游继续轮询
pending / running / in_progress / processing上游处理中继续轮询并展示 progress
completed / success / succeeded完成读取 video_url / download_url
failed / error失败展示 error,不要继续轮询
{
  "id":"vid_xxx",
  "object":"video.generation",
  "status":"completed",
  "model":"...",
  "progress":100,
  "video_url":"https://...",
  "download_url":"/v1/videos/vid_xxx/download"
}

图片生成 已开放

图片与视频共用同一个 sk-ms-... API Key 和用户积分。

接口

GET
/v1/videos/images/models读取开放图片模型、分辨率、比例、参考图上限和价格。
POST
/v1/videos/images/generations文生图 / 图生图。count 当前 1–4。

字段

model必填;从模型接口读取
prompt必填
resolution例如 1K / 2K / 4K,以模型返回为准
aspect_ratio例如 1:1 / 16:9 / 9:16
count1–4
images可选;Data URL / Base64 参考图数组
curl -X POST 'https://api.haohaoma88.top/v1/videos/images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"gpt-image-2",
    "prompt":"电影感城市夜景,雨后路面反光",
    "resolution":"2K",
    "aspect_ratio":"16:9",
    "count":2
  }'
可先传 dry_run:true 做参数与定价自检;该请求不会生成图片、不会扣积分。

统一图片 API · A / B 渠道

GET /v1/models 同时返回渠道 IMAGE(B,同步)和 IMAGE_A(A,异步)的图片型号。请始终使用响应中的 id,不要提交原始上游模型名称或猜测 ID。

GET
/v1/models读取 type=image 的开放型号;渠道 A 提供公开 ID、名称、可用分辨率/比例和按任务积分价格。
POST
/v1/images/generations传 channel:"A" + 模型公开 ID:走 A 独立异步任务;传 B 模型则保持原来的同步响应。
GET
/v1/images/tasks?channel=A&limit=50查询自己提交的图片 A 异步任务。
GET
/v1/images/tasks/{task_id}按 ID 查询自己任务的排队、下载、完成、失败状态和结果;不是别人的任务会返回 404。
# 1. GET /v1/models,选择 type=image 且 channel=IMAGE_A 的公开 id
# 2. 提交一张;非 MJ 多张须分别提交,每次独立扣费
curl -X POST 'https://api.haohaoma88.top/v1/images/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"channel":"A","model":"IMAGE_A_PUBLIC_ID_FROM_MODELS","prompt":"海边日落","resolution":"1K","aspect_ratio":"16:9","count":1}'

# 返回:{"object":"image.task","id":"ia_...","status":"queued","task_url":"/v1/images/tasks/ia_..."}
# 3. GET /v1/images/tasks/ia_... 查询;不要把 queued 当作已完成
# B 原来的 POST /v1/images/generations(不传 channel 或 channel=B)保持不变。
计费与任务安全:A 只接受单次 count=1,MJ 一次可能产生固定多张结果;只读取真实公布的售价,管理员未核实的分辨率不会出现在统一可调用目录。提交超时或状态未知时按任务 ID 查询,不要自动重新 POST 以免重复计费。

图片渠道 A · 异步任务 API

区别于上方 B 图片生成接口,A 走 /v1/image-a 独立模型目录与后台持久化队列。使用同一用户 API Key,价格按模型、分辨率在服务器实时核验。

GET
/v1/image-a/models只返回管理员开启且配置售价的模型(未核实上游成本的分辨率不允许提交);包含 count_fixed、count、resolution_prices、aspect_ratios。
POST
/v1/image-a/tasks提交一次异步图片任务,立即预扣本次生成积分,返回任务 id。
GET
/v1/image-a/tasks?limit=50查询当前账号的排队、生成、下载、完成、失败、退款核查任务,results 中返回安全的下载 URL。
POST
/v1/image-a/results/{result_id}/upscale仅管理员开启高清处理的原图可调用;必须使用原上游账号及原工作流。
curl -X POST 'https://api.haohaoma88.top/v1/image-a/tasks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"miora-midjourney-v8-2","prompt":"电影感城市街道","resolution":"720P","aspect_ratio":"16:9","count":1,"images":[]}'

# 返回:{"id":"ia_xxx","status":"queued","charged_credits":0.12}
# 轮询:GET /v1/image-a/tasks?limit=50
每次 POST 都是一个独立计费任务,count 必须为 1;非 MJ 模型想生成 2–4 张时,应逐项调用 2–4 次并分别记录任务 ID。MJ 的一次任务可返回固定多张结果,不可按返回张数重复收费。已提交上游或提交状态未知的任务不得盲目重试。示例积分为示意值,实际从 models 读取。

图片结果与历史

GET
/v1/videos/images/results?limit=50读取当前 API Key 所属账号的历史结果,limit 最大 200。
GET
/v1/videos/images/results/{result_id}/file?token=...浏览原图。优先直接使用生成响应返回的 url。
GET
/v1/videos/images/results/{result_id}/download?token=...下载单张图片。
POST
/v1/videos/images/results/batch-downloadJSON: {"ids":["img_xxx"]},返回 ZIP。

独立视频渠道 A+ · 按秒计费 默认未启用

A+ 不使用原 A 渠道或 T 账号池。拥有独立 HTTPS 上游、独立 API Key、实时余额检查和每型号独立按秒价格;只有管理员配置并核实兼容协议后才开放。

GET
/v1/a-plus/models查询已开放的 A+ 模型及每秒积分售价、可选时长范围。
GET
/v1/a-plus/generations分页读取当前用户的 A+ 视频任务、结果和状态。
POST
/v1/a-plus/generations提交异步视频任务;系统先检查独立上游余额,再预扣用户及代理结算积分。
GET
/v1/a-plus/generations/{id}读取任务的状态、扣费与完成视频地址;任何提交未知的任务不自动重试。
curl -X POST 'https://api.haohaoma88.top/v1/a-plus/generations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"model":"a_plus_MODEL_ID","prompt":"海边日落的镜头推进","duration_seconds":15,"resolution":"720p"}'

# 返回:{"id":"ap_xxx","channel":"A+","status":"queued","charged_credits":...}
# GET /v1/a-plus/generations/ap_xxx
2.5 系列固定验证 5–30 秒,其他系列固定验证 5–15 秒,单价为每秒积分乘实际请求秒数。当前包支持的上游协议是 media_studio_v1:GET /v1/balance、POST /v1/videos/generations、GET /v1/videos/{id}。如果新上游协议不一致,必须先编写对应 adapter,不可仅填 API Key 后强制开启。

账号商店 / 分销 API 已开放

账号商店支持 API 对接。为避免第三方商店权限影响视频/图片生成,商店接口使用用户在“API 接入 → 账号商店 API · 分销 Key”中创建的 rs_... Key,而不是 sk-ms-...。

GET
/v1/reseller/account-store/balance读取当前分销 Key 绑定账号的剩余积分。
GET
/v1/reseller/account-store/goods商品列表;支持 search / category / page / per_page。
GET
/v1/reseller/account-store/goods/{goods_id}商品详情与可购买规格。
POST
/v1/reseller/account-store/purchase购买账号商品并扣当前用户积分。
GET
/v1/reseller/account-store/orders读取当前 rs_ Key 自己创建的订单。
GET
/v1/reseller/account-store/orders/{order_id}查询单个订单状态、上游单号、失败原因与交付内容。
# 认证
Authorization: Bearer rs_完整Key

# 商品列表
curl 'https://api.haohaoma88.top/v1/reseller/account-store/goods?page=1&per_page=24' \
  -H 'Authorization: Bearer rs_完整Key'

# 购买
curl -X POST 'https://api.haohaoma88.top/v1/reseller/account-store/purchase' \
  -H 'Authorization: Bearer rs_完整Key' \
  -H 'Content-Type: application/json' \
  -d '{"goods_id":1,"sub_id":2,"quantity":1}'

# 查询订单
curl 'https://api.haohaoma88.top/v1/reseller/account-store/orders' \
  -H 'Authorization: Bearer rs_完整Key'
分销 Key 自动绑定创建它的登录用户及其积分钱包。完整 Key 仅在创建或重置时显示一次;可以单独停用、重置或删除,不会影响普通 sk-ms-... 生成 API。

渠道与动态能力

当前视频平台可以包含 H / C / A / S / M / K / Z / Y / B / T / D;实际返回取决于管理员是否启用、当前账号是否可见、上游是否可用以及是否配置售价。

渠道模型能力来源接入建议
H / C / A / SMedia Studio 统一模型能力同样先读模型接口,不硬编码
M / K / Z / Y管理员同步上游或本地校验目录后动态生成模型显示名称、渠道显示名称都可修改;公共模型 ID 与渠道代码才是稳定调用标识。M 在提交前会用当前模型绑定的 API Key 再读取一次上游 /models 并校验能力。
Y参考素材能力随模型变化sd-20-933(本地公共模型 y_sd_20_933_e47298d)固定为 480p / 15 秒,最多 9 图 + 3 视频 + 3 音频;仍建议以模型接口返回的 reference_limits 为准。
B本地审核目录:38 个候选模型其中 26 个按条、12 个按秒;以接口返回的 billing_unit=generation|second 为准,不要从显示名称猜计费方式。模型默认应先测试、定价、开放后再给普通用户使用。
Z时长、分辨率、参考素材能力随模型变化不要统一固定 5 秒或固定分辨率
T账号池 / 工作流能力可用性与账号池状态相关,仍应以渠道和模型接口实时结果为准
D桌面批量视频 Worker / 账号池seedance_2_0_d 由已连接的 Windows Worker 执行;支持 5-15 秒、480p/720p、图片/视频参考素材。素材须先通过本站 media/upload 上传,可用性以 Worker 在线状态为准。
IMAGE独立图片模型定价在 /v1/models 中以 type=image 出现
B 渠道目录的计费单位由后端目录强制校验:按条模型只收一次模型售价;按秒模型按“售价 × 任务时长”计费。客户端不要自行转换单位。

常见错误码

HTTP / 错误含义
400参数、模型、分辨率、时长、素材格式或模型能力不合法。M 渠道会在实际创建任务前,用该模型当前绑定的 API Key 校验上游模型与能力,尽量把上游模糊的 400 提前转换成明确的本地错误。
401 / 403API Key 无效、权限不足,或模型/图片组合尚未开放。
402用户积分不足。
404模型、任务或结果不存在,或当前账号不可见。
409同一个 Idempotency-Key 被用于不同参数、请求仍在处理中,或资源暂未就绪。
429并发、队列或上游限流。
502 / 503 / 504上游或临时网络异常。已经创建成功的异步任务应继续查询任务接口,而不是盲目重复创建。
Generation service error如果任务已经成功拿到上游任务 ID、之后轮询才失败,表示上游进入“生成阶段”后返回失败;它本身不能证明 Media Studio API 服务器故障。应结合渠道、上游任务 ID、参考素材、模型状态和上游日志排查。