# 看海无限画布 API 接入文档

更新：2026-10-19（北京时间）。本文描述本站接口，适用于软件、工作流和服务端接入。

## 1. 地址、密钥与接入顺序

Base URL：`https://yioapp.top/openapi/v1`。不要填写 `https://yioapp.top/v1`。

在本站“API管理”创建并保存完整API密钥，仅在调用方服务端使用；密钥列表的前缀不是完整密钥。不要使用上游渠道密钥。

```http
Authorization: Bearer koko_live_你的完整本站密钥
Content-Type: application/json
```

| 操作 | 方法与路径（相对Base URL） |
| --- | --- |
| 查询模型、状态与本账号价格 | GET /models |
| 查询账号余额 | GET /account |
| 上传图片或复用本人素材 | POST /files |
| 创建视频任务 | POST /videos |
| 查询任务详情 | GET /videos/{id} |
| 获取视频内容 | GET /videos/{id}/content |

先查询模型，上传素材，创建任务，保存创建响应的本站id；之后查询该id，完成后读取完整video_url或访问content接口。

## 2. 当前模型目录

以下是2026-10-19发布时的目录快照；维护状态、账号专属价格和能力以本人密钥GET /models返回为准。模型显示名称不是提交参数，请使用model ID。

| model ID | 显示名称 | 发布时状态 | 时长（秒） | resolution |
| --- | --- | --- | --- | --- |
| chaomeng-video-345b30093bb2 | 速冲!特价渠道720p Seedance 2.5 满血 (可过真人，不排队) | 可用 | 15 / 30 | 720p |
| minimaxh3 | MiniMaxH3 2K满血版 | 可用 | 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15 | 768p |
| sd2_480p_real | SD2.0 720p支持9图3视频3音频，过人脸，不排队 | 可用 | 15 | 720p |
| sd_2_5_once_720p | SD2.5满血全参30图10视频10音频，原生过人脸，不排队 | 可用 | 30 | 720p |
| seedance-2.0 | Seedance 2.0 · 卡人脸满血版 | 可用 | 5 / 10 / 15 | 720p |
| seedance-2.5 | Seedance 2.5 · 卡人脸满血版 | 维护中 | 10 / 16 / 20 / 30 | 720p |
| seedance-2.5-special | Seedance 2.5 · 不卡人脸满血版 | 维护中 | 30 | auto |
| seedance-2.5-workflow | Seedance 2.5 · 不卡人脸（90%过）满血版 | 维护中 | 30 | 720p |
| feituo_seedance25_discount_720p | 特惠 Seedance 2.5 满血 720p | 已停用 | 15 / 30 | 720p |
| lingjing-sd2.5 | Seedance2.5·不卡人脸(内置过人脸)满血版 | 维护中 | 30 | 720p |

H3虽按要求显示为“MiniMaxH3 2K满血版”，实际接入参数仍是768p，不能发送2K。模型名中的“不排队”“过人脸”等属于显示名称，不保证即时处理、审核通过或必定生成成功。

GET /models返回形如`{"models":[...]}`。检查enabled、maintenance、durations、resolutions及参考素材限制；接口新增模型时，以实时目录为准。

### 主要模型价格与参考能力

| model ID | 普通 / 会员积分 | 图片上限 | 音频上限 | 视频上限 |
| --- | --- | --- | --- | --- |
| minimaxh3 | 15 / 12 | 8，至少1张 | 3 | 不支持 |
| chaomeng-video-345b30093bb2 | 57 / 55 | 9 | 不支持 | 不支持 |
| sd2_480p_real | 50 / 45 | 9 | 3 | 3 |
| sd_2_5_once_720p | 90 / 80 | 30 | 10 | 10 |

以上为标准价格，1元=10积分。会员、后台单独定价、API专属定价可能不同，请读取本人密钥查询到的价格；不要根据模型名称或文档价格自行推算扣费。代理抽佣依后台规则结算，不是API请求字段。

## 3. 本地图片、图片URL与素材复用

推荐先上传图片，避免创建任务时携带大段Base64。POST /files使用JSON，不是multipart。

```json
{"image_b64":"data:image/jpeg;base64,替换为真实非空图片Base64"}
```

image_b64支持完整data URI或能解码为真实图片的纯Base64。系统按图片实际内容识别格式；不要把本地路径当作图片数据。

上传返回id、image_id、url、mime、name。url若以/开头，补全https://yioapp.top，并保留token等全部查询参数。以下为响应结构示意，不是可用素材：

```json
{"id":"asset_示意ID","image_id":"asset_示意ID","url":"/api/reference-assets/asset_示意ID/content/reference.jpg?token=示意令牌","mime":"image/jpeg","name":"reference.jpg"}
```

复用本人已上传的本站素材时，可向POST /files发送`{"image_url":"本人完整本站素材URL"}`；兼容旧客户端把本站素材URL放入image_b64的写法。不能通过此接口复用他人素材，也不会替你抓取任意外部URL。

外部图片URL应直接放在创建任务的image_urls里；音频用audio_urls，支持视频参考的模型用video_urls。URL必须允许服务端无需登录读取真实非空文件，不能是HTML页面、本地路径、过期链接或需要Cookie的链接。

普通参考素材按72小时保留策略清理，过期后需重新上传。不要反复复用已删除的素材。

example.com、REPLACE_WITH_REAL_ASSET_URL、示意ID和示意令牌均为占位符，禁止原样提交。下列示例中的图片和音频链接也必须替换为真实素材。

## 4. 创建任务与H3图片、音频示例

H3的本站model为minimaxh3，不是上游minimax_h3。支持5～15秒、768p、1～8张图片、最多3个音频，不支持参考视频或纯文生视频。

```bash
curl 'https://yioapp.top/openapi/v1/videos' \
  -H 'Authorization: Bearer koko_live_你的完整本站密钥' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: customer-order-20261019-001' \
  -d '{
    "model": "minimaxh3",
    "prompt": "参考图片主体和音频节奏，让小猫自然地跳舞",
    "duration": 15,
    "ratio": "9:16",
    "resolution": "768p",
    "image_urls": ["REPLACE_WITH_REAL_IMAGE_URL"],
    "audio_urls": ["REPLACE_WITH_REAL_AUDIO_URL"]
  }'
```

不用音频时省略audio_urls。比例可选9:16、1:1、3:4、4:3、16:9。duration为秒数，也兼容seconds；ratio兼容aspect_ratio。本站字段与上游直连字段不同，请勿照搬上游images/audios格式。

其他可用模型沿用相同基础结构，按GET /models指定model、duration、ratio和resolution；图片ID也可放入image_ids。reference_images/reference_audios/reference_videos支持含url的对象数组，仅在模型具备对应能力时使用。

创建响应保存本站id。每个业务订单使用唯一Idempotency-Key；同一订单的网络重试沿用原键，不能换新键重复生成。

单用户滚动60秒最多提交100条视频任务。这是提交频率规则，不是每次必须等前一条完成。上游可能另有排队或容量限制。

## 5. 查询、状态与失败原因

```bash
curl 'https://yioapp.top/openapi/v1/videos/本站任务ID' \
  -H 'Authorization: Bearer koko_live_你的完整本站密钥'
```

始终使用创建响应的本站id查询，不能改用upstream_task_id、其他渠道任务ID或返回视频URL中的ID。

| status | 含义 | 客户端处理 |
| --- | --- | --- |
| queued | 排队 | 等待后查询 |
| running | 处理中 | 等待后查询 |
| completed | 已完成 | 读取最新video_url |
| failed | 失败 | 展示failure_reason并核对退款流水 |

建议每60秒查询一次；完成或失败后停止后台轮询。为了重新获取结果地址，可以主动再查询一次任务详情。查询上游状态有同步间隔，页面未更新时先刷新原任务，不要新建重复任务。

查询响应主要字段：id、task_id、status、model、points、video_url、failure_reason、upstream_task_id、provider、created_at、updated_at。本站task_id与id表示本站任务；upstream_task_id仅用于排查。时间戳单位为秒。

失败原因优先读取failure_reason。参考素材被拒绝不代表文件一定为空，也可能是上游素材规则；通用报错不能据此认定具体哪张图片或哪项限制。

网络超时、HTTP503或没有上游编号不等于确认未接收。接收结果不明时不要自动补发，避免重复任务和扣费。退款以本站积分账本为准；不要仅凭失败文字推断已经到账。

## 6. 视频播放、下载与H3新签名链接

完成后使用本次查询返回的完整video_url，不要自行拼接上游地址、替换域名、删掉查询参数，或一直使用以前保存的旧地址。

H3现已支持上游签名直链，链接包含exp和sig，有效期由上游签发，当前为7天。有效签名链接可直接放入浏览器或播放器，无需额外Authorization。此免鉴权规则仅适用于实际返回的有效签名视频链接，不适用于本站查询和其他API接口。

如果旧任务曾返回api.mmg.lat的地址并出现401 Invalid token，请重新GET本站/videos/{id}获取最新video_url。2026-10-19已修复并更新7条历史H3任务链接。签名过期、地址仍无效或未更新时，提供本站任务id联系处理；不要重新创建付费任务。

通过本站内容接口下载时仍须带本站密钥：

```bash
curl -L 'https://yioapp.top/openapi/v1/videos/本站任务ID/content' \
  -H 'Authorization: Bearer koko_live_你的完整本站密钥' \
  -o video.mp4
```

播放器不能设置Header时，优先使用完整video_url。不要把API密钥拼进URL。若自行跟随跨域跳转，不要把本站密钥转发到其他域名。

content可能返回200视频流、支持时返回206分段内容，或307跳转。Range和拖动进度能力取决于实际渠道，不能假设所有视频都支持206。SD2.0当前通过本站流式转发；H3签名链接已验证200 video/mp4。流式转发不需要完整视频落盘，但仍会占用网络带宽与连接。

签名链接的7天有效期不是本站记录或素材保留期限，仍以各自清理策略为准。

## 7. 常见错误与排查

| HTTP / 错误码 | 含义与处理 |
| --- | --- |
| 400 EMPTY_REFERENCE_ASSET | 上传内容为空，重传原文件 |
| 400 INVALID_REFERENCE_IMAGE | 图片无法解码或格式无效，重传原图 |
| 400 REFERENCE_ASSET_EXPIRED | 素材已删除、过期或不属于当前账号 |
| 400 UNSUPPORTED_REFERENCE_URL | /files仅复用本人本站URL，外部URL放入image_urls |
| 401 | 本站密钥无效、签名视频链接失效或上游鉴权错误，先区分返回域名 |
| 402 | 积分不足 |
| 404 | 路径或任务不存在，检查/openapi/v1前缀及本站id |
| 409 | 视频未完成或不可用 |
| 429 | 提交频率或渠道容量达到限制 |
| 503 | 模型维护、渠道暂不可用或接收结果不明 |
| 502 / 504 | 网关或上游异常，先查询原任务，勿重复创建 |

“参考素材不符合要求”：记录本站id和上游编号，核对素材能否下载、实际格式、数量和模型限制；具体拒绝原因以该任务上游诊断为准。

“已完成但无法播放”：重新查询获得最新完整video_url，保留签名参数，检查内容返回video/mp4而非JSON错误。需要排查时提供本站任务id和失败时间，不要发送完整API密钥。

## 8. 文档入口

网页：https://yioapp.top/docs/api.html

Markdown：https://yioapp.top/docs/API.md

OpenAPI：https://yioapp.top/docs/openapi.json

本规范描述本站接入协议；第三方软件的“OpenAI兼容”标签不保证视频字段、状态或解析方式完全一致。