Cano API 文档

所有 `/api/v1/*` 接口都使用 Bearer Token。创建 Key 时必须明确选择图片、视频、音频、模型查询等 scope，并可设置生命周期积分预算与模型白名单；超出权限、预算或白名单会明确返回错误，不会替换成其他模型。

Authorization: Bearer cano_live_xxx

所有生成类 POST 请求都应传唯一的 Idempotency-Key。同一个 Key 与同一请求体会重放原任务；同一个 Key 对应不同请求体会返回 409，避免网络重试重复扣费。

curl -H "Authorization: Bearer $CANO_API_KEY" \
  "https://cano.gewuzhihui.com/api/v1/models?kind=VIDEO"

参考图片、视频和音频可以先上传复用，也可在生成接口中直接 multipart 上传。图片建议显式使用 kind=image-reference；Seedance 2.0 视频参考使用 kind=video-reference；生成参考音频使用 kind=video-audio-reference，并实测限制为 2-15 秒。配音音色参考仍使用 kind=audio。未知用途、无法识别或扩展名与 Content-Type 冲突的文件会直接拒绝，不会静默忽略。

curl -X POST "https://cano.gewuzhihui.com/api/v1/uploads" \
  -H "Authorization: Bearer $CANO_API_KEY" \
  -F "kind=image-reference" \
  -F "file=@./ref.png"

curl -X POST "https://cano.gewuzhihui.com/api/v1/uploads" \
  -H "Authorization: Bearer $CANO_API_KEY" \
  -F "kind=video-reference" \
  -F "file=@./motion.mp4"

curl -X POST "https://cano.gewuzhihui.com/api/v1/uploads" \
  -H "Authorization: Bearer $CANO_API_KEY" \
  -F "kind=video-audio-reference" \
  -F "file=@./rhythm.wav"

图片模型支持 cano-image-2 和 seedream-5.0-pro。Seedream 5.0 Pro 的 1K、2K、4K 均为 8 积分 / 张；未传尺寸时默认 1K。

curl -X POST "https://cano.gewuzhihui.com/api/v1/images/generations" \
  -H "Authorization: Bearer $CANO_API_KEY" \
  -H "Idempotency-Key: image-$(uuidgen)" \
  -F "model=cano-image-2" \
  -F "prompt=参考图片生成更清晰的写实产品图，保持结构比例一致" \
  -F "size=2000x2000" \
  -F "file=@./ref.png"

curl -X POST "https://cano.gewuzhihui.com/api/v1/images/generations" \
  -H "Authorization: Bearer $CANO_API_KEY" \
  -H "Idempotency-Key: image-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cano-image-2",
    "prompt": "一张写实产品摄影图，黑色工业塑料设备，棚拍柔光，细节清晰",
    "size": "3840x2160",
    "n": 1
  }'

curl -X POST "https://cano.gewuzhihui.com/api/v1/videos/generations" \
  -H "Authorization: Bearer $CANO_API_KEY" \
  -H "Idempotency-Key: video-$(uuidgen)" \
  -F "model=seedance-2.0-mini-720p" \
  -F "type=multimodal2video" \
  -F "prompt=以参考图为首帧，产品稳定，镜头缓慢环绕，写实棚拍质感" \
  -F "duration=8" \
  -F "ratio=16:9" \
  -F "file=@./product.png"

curl -X POST "https://cano.gewuzhihui.com/api/v1/videos/generations" \
  -H "Authorization: Bearer $CANO_API_KEY" \
  -H "Idempotency-Key: video-$(uuidgen)" \
  -F "model=seedance-2.0-mini-720p" \
  -F "type=multimodal2video" \
  -F "prompt=参考多张产品图生成 8 秒产品展示视频，主体结构保持一致，平稳运镜" \
  -F "duration=8" \
  -F "ratio=16:9" \
  -F "images=@./front.png" \
  -F "images=@./side.png" \
  -F "images=@./detail.png"

curl -X POST "https://cano.gewuzhihui.com/api/v1/videos/generations" \
  -H "Authorization: Bearer $CANO_API_KEY" \
  -H "Idempotency-Key: video-$(uuidgen)" \
  -F "model=seedance-2.0-mini-720p" \
  -F "type=multimodal2video" \
  -F "prompt=保持产品外观，参考视频动作和音频节奏推进镜头" \
  -F "duration=8" \
  -F "ratio=16:9" \
  -F "images=@./product.png" \
  -F "videos=@./motion.mp4" \
  -F "audios=@./rhythm.wav"

import os
import uuid
import requests

with open("product.png", "rb") as image, open("rhythm.wav", "rb") as audio:
    response = requests.post(
        "https://cano.gewuzhihui.com/api/v1/videos/generations",
        headers={
            "Authorization": f"Bearer {os.environ['CANO_API_KEY']}",
            "Idempotency-Key": f"video-{uuid.uuid4()}",
        },
        data={
            "model": "seedance-2.0-mini-720p",
            "type": "multimodal2video",
            "prompt": "保持产品外观，按参考音频节奏推进镜头",
            "duration": "8",
            "ratio": "16:9",
        },
        files=[
            ("images", ("product.png", image, "image/png")),
            ("audio_files[]", ("rhythm.wav", audio, "audio/wav")),
        ],
        timeout=60,
    )

payload = response.json()
response.raise_for_status()
assert payload["data"]["refAudioCount"] == 1, payload
print(payload["data"]["id"], payload["data"]["multipart"])

multipart 推荐字段为 images、videos、audios；同时兼容 Python 常见的 audio_files[]、reference_audios 等文件字段。服务端会按文件真实类型归类；字段声明与文件类型冲突、文件误传到文本字段或未知普通参数都会直接返回 400。成功响应中的 refAudioCount 和 multipart 是本次实际接收结果，客户端应在创建任务后校验。 除 multipart 上传外，也可用 JSON 的 refImageUrls、refVideoUrls、refAudioUrls 传外部 HTTPS 地址。视频和音频会在创建任务前真实下载并验证，生成参考音频每段必须为 2-15 秒。 音频仅用于节奏、动作、情绪或口型参考，最终旁白与配乐仍应使用音频接口或工作流 TTS / Compose。 尺寸 / 时长必须取自 GET /api/v1/models 返回的可选值，不支持的参数会报 VALIDATION_ERROR，不会静默降级。 旧客户端传 image2video 时会作为兼容别名执行，但响应中的实际 type 为 multimodal2video，并返回 modeAliasApplied=true。

下表为大额充值 8 折后的最低价。2.0 括注 API 对标价，2.5 展示国际版页面当前真实积分消耗。任务按模型基础价积分扣费（1 元 = 10 积分），优惠在充值：常态 9 折、大额最低 8 折。

curl -H "Authorization: Bearer $CANO_API_KEY" \
  "https://cano.gewuzhihui.com/api/v1/audio/voices"

curl -X POST "https://cano.gewuzhihui.com/api/v1/audio/speech" \
  -H "Authorization: Bearer $CANO_API_KEY" \
  -H "Idempotency-Key: speech-$(uuidgen)" \
  -F "model=cano-voiceover" \
  -F "text=这里是一段产品介绍配音。" \
  -F "voiceName=yangguang-xiaonanhai" \
  -F "voiceReference=@./voice.wav" \
  -F "speechSpeed=1.0"

curl -X POST "https://cano.gewuzhihui.com/api/v1/audio/music" \
  -H "Authorization: Bearer $CANO_API_KEY" \
  -H "Idempotency-Key: music-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cano-music",
    "prompt": "干净、科技感、适合产品介绍的背景音乐，无人声",
    "duration": "auto"
  }'

curl -H "Authorization: Bearer $CANO_API_KEY" \
  "https://cano.gewuzhihui.com/api/v1/jobs/cmxxx"

创建任务的响应含 id、status、cost（本次预扣积分）。 状态流转：QUEUED → RUNNING →（异步上游）SUBMITTED → SUCCEEDED / FAILED；取消中为 CANCEL_REQUESTED，完成后为 CANCELLED。响应同时记录 requested / effective / provider / model / size / duration / aliasApplied，便于核对实际执行参数。失败时返回 errorClass 与 errorMessage。

为方便把 new-api / one-api 等聚合器和 OpenAI 风格客户端直接接到 Cano，根目录 /v1 提供 newapi 兼容端点（与原生 /api/v1 互不影响）。 Base URL 直接填 https://cano.gewuzhihui.com，聚合器会自动拼 /v1/...。Key 推荐用 sk- 格式。

curl -H "Authorization: Bearer $CANO_API_KEY" \
  "https://cano.gewuzhihui.com/v1/models"

curl -X POST "https://cano.gewuzhihui.com/v1/images/generations" \
  -H "Authorization: Bearer $CANO_API_KEY" \
  -H "Idempotency-Key: compat-image-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedream-5.0-pro",
    "prompt": "一只橘猫坐在窗台，柔和晨光",
    "size": "1024x1024"
  }'

curl -X POST "https://cano.gewuzhihui.com/v1/video/generations" \
  -H "Authorization: Bearer $CANO_API_KEY" \
  -H "Idempotency-Key: compat-video-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-mini-720p",
    "prompt": "橘猫在窗台伸懒腰，镜头缓慢推近",
    "duration": 5,
    "width": 1280,
    "height": 720
  }'
# 返回 { "task_id": "cm...", "status": "queued" }

curl -H "Authorization: Bearer $CANO_API_KEY" \
  "https://cano.gewuzhihui.com/v1/video/generations/<task_id>"
# 完成时 { "task_id":"...","status":"completed","url":"https://...mp4","format":"mp4","metadata":{...} }

说明：生图为同步（内部轮询出图，最长约 4 分钟）；生视频为异步任务，先建任务拿 task_id，再轮询查询直到 completed。聚合器请把渠道超时设大一些。

统一错误结构：{ "success": false, "error": { "code": "...", "message": "...", "requestId": "..." } }，响应头也包含 x-request-id。按 code 处理，余额不足与频率限制建议退避重试。

视频模型目录中的秒价为基础价。请求实际包含参考视频时，按即梦平台视频参考秒价计费，最终积分按ceil(参考视频秒价 × (生成秒数 + 参考视频实测总秒数))计算。仅图片参考、仅音频参考或无参考视频时维持基础价。