跳到主要内容
关于我们
厦大统一认证

统一接入全球大模型,按量计费,无最低消费。

service@oceango.hk

产品

  • 模型广场
  • 计费口径
  • 免费开始

开发者

  • 文档
  • 快速开始
  • 工具接入
  • 服务状态
  • API Key 管理

公司

  • 关于我们
  • 服务条款
  • 隐私政策

支持

  • 帮助中心
  • 登录
  • 进入控制台

Powered by CMI模型能力由上游供应商提供。

所有系统运行正常

开发者文档

文档目录
工具接入 →

入门

  • 平台介绍
  • 快速开始
  • 鉴权

API 参考

  • 对话补全
  • 图像生成
  • 文本向量化
  • 重排
  • 视频生成
  • 素材库
  • 模型与路由

平台机制

  • 计费口径
  • 错误码与排查
工具接入 →

入门

  • 平台介绍
  • 快速开始
  • 鉴权

API 参考

  • 对话补全
  • 图像生成
  • 文本向量化
  • 重排
  • 视频生成
  • 素材库
  • 模型与路由

平台机制

  • 计费口径
  • 错误码与排查

素材库

上传一次、由平台长期保存,之后在视频请求里用 `asset://ast_…` 引用。

工作方式#

素材库保存你的参考图片、视频与音频。上传后得到一个素材 ID(ast_…)与引用地址(asset://ast_…),把引用地址填进视频请求的参考素材位置即可,不必每次重新上传,也不必自己准备公网地址。素材一直保存到你删除为止。

  1. 1

    上传

    POST /v1/library/assets,multipart 上传文件,或给一个公网 URL 由平台拉取。

  2. 2

    等待就绪

    新素材处于 processing,平台校验格式与尺寸并生成预览,通常几秒内变为 ready。

  3. 3

    为模型准备与审核

    POST .../assets/{id}/prepare 指定模型,再轮询 GET .../assets/{id}/readiness?model=...;需要审核的模型须取得 approved。

  4. 4

    引用

    在 /v1/videos 的 input_reference 或方舟协议 content[] 的 url 里写 asset://ast_…。

  5. 5

    管理

    列表、改名、分组、删除;也可以在控制台的 素材库 页面可视化管理。

只能引用自己的素材
素材归属于 API Key 所在的账号。Key 绑定了项目时,只能看到并引用该项目的素材与未归属项目的素材。引用不存在或无权访问的素材一律返回 asset_not_found。

支持的格式与上限#

类型格式大小其他要求
图片JPEG / PNG / WebP / GIF / BMP / TIFF / HEIC / HEIF≤ 30 MB宽高 300–6000 像素,宽高比 0.4–2.5
视频MP4 / MOV(H.264 / H.265)≤ 200 MB时长 2–30 秒,帧率 24–60,宽高与宽高比同图片
音频MP3 / WAV≤ 15 MB时长 2–30 秒

格式按文件内容判断,与扩展名和 Content-Type 无关。这是入库时的通用上限;具体模型对引用数量、总时长、分辨率可能有更严的要求,以模型说明为准。

上传素材#

POST /v1/library/assets。支持三种写法:multipart 文件上传(推荐,大视频请用这种)、JSON 给 url 由平台拉取、JSON 给 data(base64 或 data URI,原件不超过 10 MB)。

filefile
multipart 文件字段。与 url / data 三选一。
urlstring
JSON 方式:公网 http(s) 地址,平台去拉取。内网与本机地址会被拒绝。
datastring
JSON 方式:base64 或 data:image/png;base64,…。
namestring
展示名,缺省取文件名。
group_idstring
放入某个素材组(grp_…),缺省为未分组。

multipart 上传

bash
curl https://cmitoken.xmu.edu.my/v1/library/assets \  -H "Authorization: Bearer $OGROUTER_API_KEY" \  -F file=@./hero.png \  -F name=主角-正面 \  -F group_id=grp_7312894470000000

从公网地址导入

bash
curl https://cmitoken.xmu.edu.my/v1/library/assets \  -H "Authorization: Bearer $OGROUTER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "url": "https://example.com/hero.png",    "name": "主角-正面"  }'

响应(201)

json
{  "id": "ast_7312894471029760",  "object": "asset",  "uri": "asset://ast_7312894471029760",  "kind": "image",  "purpose": "general",  "name": "主角-正面",  "group_id": "grp_7312894470000000",  "project_id": null,  "status": "processing",  "media_type": "image/png",  "size_bytes": 2310455,  "preview_url": "https://cmitoken.xmu.edu.my/v1/assets/library/u/.../original.png?exp=...&sig=...",  "use_count": 0,  "deduplicated": false,  "created_at": "2026-09-29T08:00:00Z",  "updated_at": "2026-09-29T08:00:00Z"}
重复上传不会重复占用额度
内容与你已有的某个素材完全相同时,返回的是已有那一条(HTTP 200,deduplicated: true),不新占存储。

等待处理完成#

status含义能否引用
processing正在校验格式、读取尺寸时长、生成缩略图不能,引用返回 asset_not_ready
ready本地处理完成还须为目标模型 prepare 并查询 readiness
rejected未通过校验,见 reject_code 与 reject_reason不能,引用返回 asset_rejected

GET /v1/library/assets/{id}?wait=10 会最多等待 10 秒直到素材离开 processing,比短间隔轮询更省请求。

等待就绪

bash
curl "https://cmitoken.xmu.edu.my/v1/library/assets/ast_7312894471029760?wait=10" \  -H "Authorization: Bearer $OGROUTER_API_KEY"

常见的 reject_code:dimension_out_of_range(宽高超范围)、aspect_ratio_out_of_range(宽高比超范围)、duration_out_of_range(时长超范围)、fps_out_of_range(帧率超范围)、probe_failed(文件损坏或无法解码)。被拒的素材不占用存储额度。

为目标模型准备与审核#

本地 ready 只表示文件处理完成。真人素材需要为实际生成模型单独提交准备,并主动查询审核结果;上传或登记成功不能替代审核通过。新增接口在部署并开通对应模型后可用,缺少兼容能力或审核配置时返回 unsupported。

提交准备:已就绪 200,异步处理中 202

bash
curl -i https://cmitoken.xmu.edu.my/v1/library/assets/ast_7312894471029760/prepare \  -H "Authorization: Bearer $OGROUTER_API_KEY" \  -H "Content-Type: application/json" \  -d '{"model":"doubao-seedance-2-0-fast-260128"}'

查询准备与审核结果(200)

bash
curl -i "https://cmitoken.xmu.edu.my/v1/library/assets/ast_7312894471029760/readiness?model=doubao-seedance-2-0-fast-260128" \  -H "Authorization: Bearer $OGROUTER_API_KEY"

model 必填,须与随后的视频请求一致且在 Key 的权限内。后台主动查询审核状态,客户端按 Retry-After 查询本站 readiness,未给间隔时建议每 3 秒查询。准备接口不会创建视频任务或预扣视频生成费用。重复准备复用记录,换模型需重新查询。

status含义与下一步
not_prepared尚未准备,调用 prepare
preparing准备或审核中,继续查询
ready该模型至少有一条可用生成通路,可以提交同模型任务
failed准备或审核失败,查看 reason;按 retryable 判断能否重试
unsupported类型或能力不兼容、审核配置未开通;换模型或联系支持

review_status:not_submitted 尚未提交审核或该模型无需审核;pending 等待结果;approved 已通过查询确认;failed 未通过;unknown 结果未明,不得按通过处理。必须单独查询返回 Active 后才映射为 approved,上传返回素材 ID 不能代替审核结果。协议没有列出完整原始状态枚举,程序应使用本站 status 与 review_status,不从其它原始值猜测通过。

已查询确认审核通过的结果

json
{  "asset_id": "ast_7312894471029760",  "model": "doubao-seedance-2-0-fast-260128",  "status": "ready",  "review_status": "approved",  "upstream_status": "Active",  "retryable": false,  "updated_at": "2026-10-19T08:00:06Z"}
需要审核时不能通过直接 URL 绕过
需要真人素材审核的生成通路只接受本站 asset://ast_... 引用;直接公网 URL 或内联参考返回 asset_reference_unsupported。纯文本生成不受影响,其它已支持 URL 参考的模型保持各自能力。ready + not_submitted 只表示该模型无需素材审核,不是取得了真人审核结论。审核通过也不替代客户取得合法肖像使用授权。

在视频请求中引用#

OpenAI 协议把引用地址写进 input_reference(也接受 {"asset_id": "ast_…"});方舟协议写进 image_url / video_url / audio_url 的 url。提示词里可用“图片1、视频1”按出现顺序指代参考素材。

OpenAI 协议

bash
curl https://cmitoken.xmu.edu.my/v1/videos \  -H "Authorization: Bearer $OGROUTER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "doubao-seedance-2-0-260128",    "prompt": "图片1中的人物缓缓转身,镜头推近",    "seconds": 5,    "resolution": "720p",    "input_reference": "asset://ast_7312894471029760"  }'

方舟协议:图片 + 参考视频

bash
curl https://cmitoken.xmu.edu.my/api/v3/contents/generations/tasks \  -H "Authorization: Bearer $OGROUTER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "doubao-seedance-2-0-260128",    "content": [      { "type": "text", "text": "图片1中的人物按视频1的运镜走进画面" },      {        "type": "image_url",        "role": "reference_image",        "image_url": { "url": "asset://ast_7312894471029760" }      },      {        "type": "video_url",        "role": "reference_video",        "video_url": { "url": "asset://ast_7312894471029999" }      }    ],    "resolution": "720p",    "duration": 5  }'
引用在计费之前检查
本地处理、模型素材准备与审核都在视频任务提交及预扣前检查。asset_preparing、asset_review_failed、asset_reference_unsupported 不创建视频任务,不预扣视频生成费用。平台按所选模型的素材协议转换引用;客户始终使用本站 URI。

Python:上传、本地处理、模型审核、生成

python
import os, time, requests
API = "https://cmitoken.xmu.edu.my/v1"MODEL = "doubao-seedance-2-0-fast-260128"HEADERS = {"Authorization": f"Bearer {os.environ['OGROUTER_API_KEY']}"}
def checked(response):    response.raise_for_status()    return response.json()
# 1. Upload and wait for local processing.with open("portrait.png", "rb") as source:    asset = checked(requests.post(API + "/library/assets", headers=HEADERS,                                 files={"file": source}, timeout=120))asset_path = API + "/library/assets/" + asset["id"]deadline = time.monotonic() + 300while asset["status"] == "processing":    if time.monotonic() >= deadline:        raise TimeoutError("Local asset processing timed out")    asset = checked(requests.get(asset_path, params={"wait": 10},                                 headers=HEADERS, timeout=30))if asset["status"] != "ready":    raise RuntimeError(asset.get("reject_reason", "Local validation failed"))
# 2. Prepare for this model. Upload success is not review approval.response = requests.post(asset_path + "/prepare", headers=HEADERS,                         json={"model": MODEL}, timeout=60)state = checked(response)deadline = time.monotonic() + 300while state["status"] == "preparing":    if time.monotonic() >= deadline:        raise TimeoutError("Asset review timed out; resume with GET readiness")    delay = max(1, min(30, int(response.headers.get("Retry-After", "3"))))    time.sleep(delay)    response = requests.get(asset_path + "/readiness", params={"model": MODEL},                            headers=HEADERS, timeout=30)    state = checked(response)if state["status"] != "ready" or state["review_status"] not in ("approved", "not_submitted"):    raise RuntimeError(state.get("reason", "Asset is not ready for this model"))
# 3. Submit using the same model and the site's asset URI.# Keep this key when retrying this business operation.task = checked(requests.post(API + "/videos", headers={**HEADERS,    "Idempotency-Key": "portrait-video-20261019-001"}, json={    "model": MODEL,    "prompt": "A slow, natural turn of the person in image 1",    "seconds": 5,    "input_reference": asset["uri"],}, timeout=60))print(task["id"])

管理素材与分组#

方法路径说明
GET/v1/library/assets列表,按创建时间倒序。参数 group_id(ungrouped 表示未分组)、kind、status、q(按名称搜)、cursor、limit
GET/v1/library/assets/{id}详情;?wait=10 等待处理完成
POST/v1/library/assets/{id}/prepare为指定模型准备并提交审核(JSON model)
GET/v1/library/assets/{id}/readiness查询指定模型的可用性和审核结果(必填 query model)
PATCH/v1/library/assets/{id}改名 name、移组 group_id(null 表示移出到未分组)
DELETE/v1/library/assets/{id}删除:立即不可引用并归还额度,已提交的任务不受影响
GET/v1/library/assets/{id}/content302 到 1 小时有效的下载地址;?variant=thumb 取缩略图,poster 取视频封面
GET / POST/v1/library/groups列出 / 新建素材组(name、description)
GET / PATCH / DELETE/v1/library/groups/{id}查看 / 修改 / 删除组;组内有素材时删除需加 ?cascade=true(一并删除)
GET/v1/library/usage存储用量与额度

分页列表

bash
# 第一页curl "https://cmitoken.xmu.edu.my/v1/library/assets?kind=image&limit=30" \  -H "Authorization: Bearer $OGROUTER_API_KEY"
# 下一页:把上一页的 next_cursor 原样传回curl "https://cmitoken.xmu.edu.my/v1/library/assets?kind=image&limit=30&cursor=ast_7312894471029000" \  -H "Authorization: Bearer $OGROUTER_API_KEY"

改名、移出分组、删除

bash
curl -X PATCH https://cmitoken.xmu.edu.my/v1/library/assets/ast_7312894471029760 \  -H "Authorization: Bearer $OGROUTER_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "name": "主角-定稿", "group_id": null }'
curl -X DELETE https://cmitoken.xmu.edu.my/v1/library/assets/ast_7312894471029760 \  -H "Authorization: Bearer $OGROUTER_API_KEY"

响应里的 preview_url、thumb_url、poster_url 是 1 小时有效的签名地址,适合直接放进 <img> / <video>,不要长期保存;需要时重新请求详情即可。

删除生效与副本清理
删除后本站引用立即失效,并归还本地存储额度;已经提交的视频任务不受影响。本站原文件由后台异步清理。当前上游协议没有删除接口,已登记的审核副本需要向上游申请人工清理,不承诺自动删除或同步销毁。登记结果未知时也需人工核对。

存储额度#

每个账号有免费存储额度与硬上限,按用户等级给出,以 GET /v1/library/usage 的返回为准。处理中与可用的素材计入用量,删除或被拒即归还。

查询用量

bash
curl https://cmitoken.xmu.edu.my/v1/library/usage \  -H "Authorization: Bearer $OGROUTER_API_KEY"
# {"used_bytes": 734003200, "asset_count": 58, "free_bytes": 1073741824,#  "hard_cap_bytes": 53687091200, "overage_billing": false}
超出额度时
上传后会超过免费额度时返回 402 storage_payment_required,超过硬上限时返回 403 storage_quota_exceeded。目前超出免费额度后暂不能继续上传(overage_billing 为 false),按量计费开放后会在此说明。

错误码#

codeHTTP含义建议
asset_not_found404素材不存在、已删除或不属于当前账号检查 ID;不要重试
asset_not_ready409素材仍在处理中用 ?wait=10 等待后再提交
asset_preparing409模型素材准备或审核中按 Retry-After: 3 查询 readiness
asset_review_failed422准备或审核未通过查看 readiness.reason 和 retryable
asset_reference_unsupported400类型或引用协议不兼容,或试图绕过审核用兼容类型及本站素材引用
asset_rejected422素材未通过校验按 reject_reason 换一个文件
asset_kind_mismatch400素材类型与引用位置不符图片放 image_url,视频放 video_url
asset_unsupported_format400格式不在支持范围内换成上表中的格式
asset_too_large413超过该类型的大小上限压缩后再传
storage_payment_required402超出免费存储额度删除不再使用的素材
storage_quota_exceeded403超出存储硬上限删除不再使用的素材

错误响应的整体结构与重试建议见 错误码。

上一篇视频生成下一篇模型与路由

本页目录

  • 工作方式
  • 支持的格式与上限
  • 上传素材
  • 等待处理完成
  • 为目标模型准备与审核
  • 在视频请求中引用
  • 管理素材与分组
  • 存储额度
  • 错误码