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。返回列表同时包含开放的视频模型和已经定价开放的图片模型。

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	说明
image	image_references / start_image / end_image	参考图或首尾帧
video	video_references / input_video	参考视频或视频超分源视频
audio	audio_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
`count`	1–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 做参数与定价自检；该请求不会生成图片、不会扣积分。

图片结果与历史

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。

账号商店 / 分销 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；实际返回取决于管理员是否启用、当前账号是否可见、上游是否可用以及是否配置售价。

渠道	模型能力来源	接入建议
H / C / A / S	Media 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	账号池 / 工作流能力	可用性与账号池状态相关，仍应以渠道和模型接口实时结果为准
IMAGE	独立图片模型定价	在 `/v1/models` 中以 `type=image` 出现

B 渠道目录的计费单位由后端目录强制校验：按条模型只收一次模型售价；按秒模型按“售价 × 任务时长”计费。客户端不要自行转换单位。

常见错误码

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

统一调用视频与图片能力

鉴权与 Base URL

Base URL

Authorization

统一模型发现

视频生成

素材上传

视频超分

任务状态与下载

图片生成 已开放

接口

字段

图片结果与历史

账号商店 / 分销 API 已开放

渠道与动态能力

常见错误码

图片生成已开放