# Coinseed 创作 API 与使用指南
文档修订号：**20261021-muse-provider-selector-v7**。正式价格与开放规格的目录版本（`GET /create/pricing` 的 `revision`，如 `20261017-muse-portrait-docs`）和本说明文本修订号独立：目录版本不代表本页说明文本版本。本次页面读取时间仅表示获取目录的时间，不是目录或文档更新时间。
[模型广场：全部模型、多个提供方与价格](/create/models)。`GET /create/model-catalog`与`GET /create/pricing`共用同一正式目录，每个服务的`providers`列出公开来源名称、开通状态、最近样例检测和`prices`。通道配置约30秒更新，过期状态标记为未知；检测不是成功率保证。Muse提供方为`muse-laoda`与`muse-laozeng`，均已开通。模型ID仍为`muse-spark`、`muse-image`、`muse-video`；普通Key可在这三个模型的普通生成POST中，将可选请求头`X-Coinseed-Provider`设为`muse-laoda`或`muse-laozeng`选择本人已授权来源；不指定仍按当前路由优先级调度。显式来源错误不自动换源或重发，已受理或结果未知的原单不自动跨来源重发。
服务地址：`https://api.coinseed.net`。可视化完整文档：[使用文档](https://api.coinseed.net/create/docs)。
参数与开放范围核对于 **2026-10-21** 的线上目录。正式金额和开放状态以 `GET /create/pricing` 为准；下面的金额仅解释计费，不覆盖实时目录。`open: false`、`price_status: pending`、规格不匹配或账号/Key 无权限时不能提交。参数已实现、私有测试通过和对普通客户开放是不同状态。
START HERE
## 最近更新（2026-10-21）
本次新增Muse已授权来源选择：普通Key可在三个Muse模型的生成POST中携带可选请求头X-Coinseed-Provider；不指定仍按原优先级调度。补充HTTP与Python SDK示例、显式来源错误和未知结果处理。价格、模型权限、已声明开放规格与正式目录版本不变。
- 对话：长剧本输入最多128条消息、合计1,048,576个Unicode字符；M3默认及保护输出上限32,768 token，Spark不设本站输出token上限。支持本地文字文件提取；M3另可理解最多4张本地图片。
- 图片：Muse文字/单图编辑的完整比例见实时目录；Nano 2.1/Pro支持五种常规比例；MiniMax image-01另支持512–2048像素、8的倍数的自定义宽高。具体模式和限制见各章节。
- Muse视频：老曾Muse视频支持文字、首帧和单图弱参考三种输入方式，时长可选1–10秒及12/15秒，画幅可选16:9、9:16、1:1、4:3、3:4、2:3、3:2。按所选时长与画幅交付，必要时裁剪原片，不延长或循环；¥0.05/秒。
- Omni：4/6/8/10秒，文字、首帧、首尾帧及1–3图素材均支持横竖屏；原生360P/720P，可免费本地放大至1080P，¥0.05/秒。 单图ingredients的原有首帧兼容保留。
- H3：四个固定档位、质量档文字/首帧/首尾帧、已验音频/视频原声、多图及max完整规格见对应章节。
- Coinseed超分：独立上传与H3同工作流接续的超分部分均为2K 0.04元/实际秒、最低0.20元；4K 0.08元/实际秒、最低0.40元。H3基础生成费另计；保留原片，无需下载再上传。
- 音频：保留Gemini/MiniMax配音，增加Suno V6纯配乐0.99元/次，通常两首MP3；WAV 0.09元/首。文件14天内及时下载。
- 余额：自己的API Key可免费调用GET /api/usage/token/查询人民币钱包和Key额度。
## 快速开始
可使用网页或 API 创作图片、视频、配音，或进行文字对话。两种方式共用 Coinseed 账号与余额；**只有异步服务进入任务/作品历史**，原生同步图片、配音和网页对话采用本页临时结果，需及时下载。
[↗**用网页创作**选择模型、填写提示词，查看进度并下载作品。
打开创作台 →](https://api.coinseed.net/create)[⌘**接入你的工具**创建个人 API Key，按模型选择异步任务、同步生成或流式对话接口。
查看接入流程 →](#api)
**第一次使用**先[注册账号](https://api.coinseed.net/sign-up)，把用户名或用户 ID 发给管理员。确认收款并开通模型权限后，网页和 API 才能生成。新账号初始余额为零。
### 先选适合你的模型
下表列出本次目录快照的全部27项服务，开放状态仅限该服务已列完整规格；实时变化、各来源状态及具体参数以[模型广场](/create/models)、[完整目录](/create/model-catalog)及对应章节为准。报价不等于开放，账号与API Key仍须具备权限。
| 模型 ID | 当前客户范围 | 状态 | 目录报价口径 |
| --- | --- | --- | --- |
| `h3-test` | 单图参考4–15秒；视频参考仅测试档4秒横屏、2秒已核验视频，可加1图；每单1个作品。 新增参考音频、多图及max仅限目录列出的完整已验规格。 | 已开放，限完整规格 | ¥0.05/所选名义输出秒 |
| `h3-custom1` | 4–15秒；含首张参考图；每单1个作品。 新增参考音频、多图及max仅限目录列出的完整已验规格。 | 已开放，限完整规格 | ¥0.08/所选名义输出秒 |
| `h3-quality` | 4–15秒；含首张参考图；每单1个作品。另有6秒竖屏文字、首帧、首尾帧方式。 新增参考音频、多图及max仅限目录列出的完整已验规格。 单张参考图、5秒横屏可选同机接续2K/4K：2K ¥0.04/实际秒、最低¥0.20；4K ¥0.08/实际秒、最低¥0.40，基础生成费另计。 | 已开放，限完整规格 | ¥0.15/所选名义输出秒 |
| `omni-flash` | 4/6/8/10秒，文字、首帧、首尾帧及1–3图素材均支持横竖屏；原生360P/720P，可免费本地放大至1080P，¥0.05/秒。 | 已开放，限完整规格 | ¥0.05/所选名义输出秒 |
| `muse-video` | 老曾Muse视频支持文字、首帧和单图弱参考三种输入方式，时长可选1–10秒及12/15秒，画幅可选16:9、9:16、1:1、4:3、3:4、2:3、3:2。按所选时长与画幅交付，必要时裁剪原片，不延长或循环；¥0.05/秒。 | 已开放，限完整规格 | ¥0.05/所选名义输出秒 |
| `veo-3.1-lite` | 原生8秒720P，首帧、首尾帧和1–3图素材均支持横竖屏；可免费本地放大至1080P，¥0.40/条。 | 已开放，限完整规格 | ¥0.05/所选名义输出秒 |
| `veo-3.1-fast` | 原生8秒720P，首帧、首尾帧和1–3图素材均支持横竖屏；可免费本地放大至1080P，¥0.40/条。 | 已开放，限完整规格 | ¥0.08/所选名义输出秒 |
| `nano-banana-2.1` | 文字生图或1–3张有序参考图；五种比例均支持每单1–4张，按实际成功交付张数¥0.10/张，参考图不另收费，像素以原图为准。 | 已开放，限完整规格 | ¥0.1/交付张 |
| `coinseed-upscale-1080p` | 逐帧AI细节处理，效果因素材而异；开放768×1344的24/362帧及720×1280的96/360帧，均24fps并带AAC；按实际帧数÷24计费。 | 已开放，限完整规格 | ¥0.02/核验视频秒；最低¥0.1/单 |
| `coinseed-upscale-2k` | 独立上传：24fps H.264 MP4、SDR 8bit yuv420p，25–384帧、短边至少270、像素数不超过1920×1080、宽高比不超过2.1；无音轨或单条AAC音轨。保持原帧数、比例和音轨，不自动转码不合规输入。2K/4K表示短边1440/2160。服务繁忙时进入准备队列；准备时间可能较久。等待时间不计入视频秒数。 | 已开放，限完整规格 | ¥0.04/核验视频秒；最低¥0.2/单 |
| `coinseed-upscale-4k` | 独立上传：24fps H.264 MP4、SDR 8bit yuv420p，25–384帧、短边至少270、像素数不超过1920×1080、宽高比不超过2.1；无音轨或单条AAC音轨。保持原帧数、比例和音轨，不自动转码不合规输入。2K/4K表示短边1440/2160。服务繁忙时进入准备队列；准备时间可能较久。等待时间不计入视频秒数。 | 已开放，限完整规格 | ¥0.08/核验视频秒；最低¥0.4/单 |
| `nano-banana-pro` | 文字生图或1–3张有序参考图；五种比例均支持每单1–4张，按实际成功交付张数¥0.15/张，参考图不另收费，像素以原图为准。 | 已开放，限完整规格 | ¥0.15/交付张 |
| `veo-3.1-lite-low-priority` | 首帧/首尾帧；普通参考包含在基础价。720P；本地1080P普通放大免费，Google1080P另计。 | 未开放 | ¥0.03/所选名义输出秒 |
| `gemini-tts` | 30种系统音色；每次最多120个Unicode字符；24kHz单声道PCM WAV。 | 已开放，限完整规格 | ¥0.01/次 |
| `muse-spark` | Chat Completions和原生Responses，支持普通JSON / SSE文字对话、文本数组、developer及文本工具历史；每次完整回复¥0.01。支持本次输入的文字上下文，图像理解、实际工具执行及服务端历史续接未开放。 | 已开放，限完整规格 | ¥0.01/次 |
| `MiniMax-M3` | 普通JSON / SSE文字对话；按实际输入、输出和缓存读取token结算。每次最多128条消息、合计最多1,048,576个Unicode字符（字符保护上限，非token数）、默认及保护上限32,768输出token，可指定更小上限。 可附最多4张本地PNG/JPEG/WEBP图片，每张最多10MB（模型服务要求）；PDF/DOCX仅本地提取正文文字。 | 已开放，限完整规格 | 输入/输出/缓存读取：¥4.2/¥16.8/¥0.84 每百万token |
| `speech-2.8-turbo` | 常规文字配音，male-qn-qingse、正常语速、MP3；先预留上限，再按供应商实际计费字符退差。仅本页临时下载。 | 已开放，限完整规格 | ¥0.0004/供应商计费字符 |
| `speech-2.8-hd` | 常规文字配音，male-qn-qingse、正常语速、MP3；先预留上限，再按供应商实际计费字符退差。仅本页临时下载。 | 已开放，限完整规格 | ¥0.0007/供应商计费字符 |
| `image-01` | 文字生图；8种比例或自定义宽高512–2048像素、8的倍数；每次1张，同步返回，仅本页临时下载。实际交付尺寸以解码文件为准；人物参考图与编辑未开放。 | 已开放，限完整规格 | ¥0.05/交付张 |
| `image-01-live` | 文字生图；7种比例；每次1张，同步返回，仅本页临时下载。实际交付尺寸以解码文件为准；人物参考图与编辑未开放。 | 已开放，限完整规格 | ¥0.05/交付张 |
| `muse-image` | 文字生图或单图编辑；比例按实时目录选择，每单1张原图，原生像素以实际交付为准；单图编辑不加价。 | 已开放，限完整规格 | ¥0.1/交付张 |
| `h3-turbo` | 6秒档，仅单张参考图片、固定方向和采样参数；输出帧数以原生合同为准。 | 已开放，限完整规格 | ¥0.08/所选名义输出秒 |
| `h3-custom2` | 6秒档，仅单张参考图片、固定方向和采样参数；输出帧数以原生合同为准。 | 已开放，限完整规格 | ¥0.15/所选名义输出秒 |
| `h3-custom-lite` | 4秒档，仅单张参考图片、固定方向和采样参数；输出帧数以原生合同为准。 | 已开放，限完整规格 | ¥0.05/所选名义输出秒 |
| `h3-custom-detail` | 6秒档，仅单张参考图片、固定方向和采样参数；输出帧数以原生合同为准。 | 已开放，限完整规格 | ¥0.225/所选名义输出秒 |
| `kie-suno-v6` | 纯音乐 · 每次最多2首 MP3 · 可按首转换 WAV | 已开放，限完整规格 | ¥0.99/次 |
| `kie-suno-wav` | 将本人已完成的音乐曲目转换 WAV；原 MP3 保留 | 已开放，限完整规格 | ¥0.09/首 |
内部Qwen本轮不上线，免费CPU普通缩放不作为AI超分售卖。不会自动替换你选择的模型。
目录里某模型的总览 `input_modes`、`supported_seconds` 或简介可能描述完整能力合同；还须核对 `variants.open` 与完整规格列表（`available_specs` / `accepted_specs`、H3 `reference_specs`、Muse `extended_specs`、AI超分 `accepted_input_specs`、原生媒体 `native_media_specs`）。不能把不同记录的图数、时长、方向交叉拼接。历史开放范围也不等于每个组合都有独立真实样本，平台不承诺固定耗时或每次画质一致。
YOUR ACCOUNT
## 账号、余额与 API Key
### 注册与开通
- 在[注册页](https://api.coinseed.net/sign-up)创建账号，记录用户名；用户 ID 可在[个人资料](https://api.coinseed.net/profile)查看。
- 按与管理员约定的渠道付款。闲鱼付款后提供订单号和本站账号，管理员核实到账，再开通客户模型权限并充值。
- 打开[钱包](https://api.coinseed.net/wallet)核对余额。使用充值码时，每个码只能兑换一次；兑换余额与模型权限开通是两件事。
- 开通后重新登录[创作台](https://api.coinseed.net/create)。页面仍显示“账号未开放”时，请提供用户 ID 联系管理员。
当前采用闲鱼收款、管理员核实到账后手工充值，暂不提供站内自助支付。付款前请确认本站用户 ID 与约定金额；充值后到钱包核对余额。付款或充值有疑问，请保留原订单号联系管理员，不要重复付款。
### 创建个人 API Key
- 登录[API Key 管理](https://api.coinseed.net/keys)，新建一个专用 Key，例如“我的视频工具”。
- 设置有效期、额度上限和需要的模型权限。H3 还需允许 `coinseed-asset` 素材上传模型。
- 把 Key 保存到你的服务端环境变量。用 `Authorization: Bearer YOUR_API_KEY` 调用下面的接口。
**一个余额，两种用法**API Key 的额度上限是额外限制，不会创造余额。网页生成和个人 API 调用都会扣同一账号余额。密钥过期、额度不足、模型白名单缺少素材模型，都可能阻止调用。
Key 的生成额度用尽时，仍可用未过期、未禁用的原 Key 免费查询本人已有、已付费的异步任务的状态、成品列表，并进行本人认证下载、HEAD/Range 和重复读取。账号、IP、任务归属及其他权限检查照常，不能跨账号读取；新生成仍须满足钱包余额与 Key 额度。具体入口见[异步任务与下载](#lifecycle)。
无需向管理员提供密码、验证码或 API Key。发现 Key 泄露时，在密钥管理中禁用或删除旧 Key，再创建新 Key。不要把密钥写进网页源代码、公开仓库或分享链接。
### 使用 API Key 查询人民币余额
`GET https://api.coinseed.net/api/usage/token/`，使用自己的 API Key，无需网页登录，也不用传用户 ID。查询免费，不扣生成额度。
先将 Key 保存到服务端环境变量 `COINSEED_API_KEY`，再查询：
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/api/usage/token/' \
-H "Authorization: Bearer $COINSEED_API_KEY"
```
成功响应节选：
```json
{
"code": true,
"message": "ok",
"data": {
"currency": "CNY",
"account_balance_cny": "7.30",
"key_remaining_cny": "1.46",
"key_used_cny": "0.73",
"unlimited_quota": false
}
}
```
| 字段 | 含义 |
| --- | --- |
| `currency` | `CNY`，人民币元 |
| `account_balance_cny` | Key 所属账号的钱包余额，与网页共用 |
| `key_remaining_cny` | 这个 Key 的剩余额度上限；不限额时为 `null`，显示“不限额” |
| `key_used_cny` | 这个 Key 的累计使用金额，不是全账号消费 |
| `unlimited_quota` | Key 是否不限额；不限额仍会扣账号余额 |
金额字段是保留两位小数的字符串，客户端可直接显示 `¥7.30`，无需自行换算点数。实际扣费仍使用精确额度，低于一分钱的余额可能显示为 `0.00`。账号余额与 Key 限额不能相加；新生成还需满足有效期和模型权限等条件。
旧字段 `total_available`、`total_used`、`total_granted` 保留原始内部额度单位，仅供兼容，不能直接当作人民币展示。客户端应检查 `code: true`、`currency: CNY` 和金额字段是否存在；缺少新字段表示服务端版本尚未支持，不能当作零余额。
此接口只返回 Key 所属账号的余额。额度用尽或已过期的 Key 仍可只读查询余额；明确禁用、已删除的 Key 或已禁用账号无法查询。这不会恢复生成权限。
#### 查询频率与429处理
余额查询单独按已认证账号限流：每60秒最多60次，同账号多个Key共享，与登录、注册等敏感操作的20分钟窗口分开。全站API防滥用限流仍有效。建议客户端把同一账号的并发查询合并，短时缓存10–30秒，生成完成或充值后再刷新；不要每个模型分别轮询同一钱包。
遇到HTTP 429时读取Retry-After响应头或JSON的retry_after秒数，等待后再查。返回的message和error.message说明余额查询过于频繁；error.code为balance_rate_limited。保留上次已知余额并标注“暂未更新”，首次查询失败显示“暂时无法获取”，不要显示零余额、Key失效或未知错误，也不要立即循环重试。查询始终免费，不扣生成额度。
CREATOR WORKCOINSEED
## 网页生成与下载
先登录[创作台](https://api.coinseed.net/create)，选择已开放的模型。图片、视频、超分、配音和对话按各自流程工作：
| 类型 | 提交与进度 | 结果保存 |
| --- | --- | --- |
| H3、Coinseed、Muse视频与图片、AI超分、Suno音乐 | 提交一次，保存任务号；后台继续生成，轮询原任务 | 成功后进入“我的作品”，本人认证下载；历史文件不承诺永久保留 |
| 原生 MiniMax 图片/配音（以目录开放为准） | 同步HTTP返回图片JSON或MP3；没有异步任务号 | 仅当前页临时文件，最多5份；立即下载，刷新/关闭/换账号会清除 |
| Muse Spark / MiniMax M3对话（分别核对目录） | 普通JSON或SSE；网页显示流式文字 | 本页对话，可下载TXT；不会进入视频任务库，刷新或换账号会清除 |
生成前填写提示词并选择已开放的完整规格。H3标准方式需一张PNG/JPG/WebP参考图；视频参考、Muse内联图、Coinseed素材和超分各有独立上传流程。不要把不同服务的素材ID直接互换。
任务排队、网络断线或“等待核对”不等于失败。异步服务先查询原任务，原生同步/对话先核对用量与提交时间；停止接收、关页面都不保证取消供应商执行。页面不会自动重发生成。再次点击生成或发送是新请求，可能再次计费。
### 提示词示例
蓝色陶瓷茶壶放在木桌上，窗外自然光从左侧照入；一缕蒸汽缓缓升起，镜头轻微向前推进，保持茶壶形状和纹理稳定，写实摄影。生成结果由模型输出，同一提示词再次生成也可能不同。需要不同内容、不同档位或重新生成时，会产生新的订单。
H3 · COMMON CONTRACT
## H3 单图参考视频
用一张参考图确定主体，再用文字描述动作和镜头。三个档位的请求结构相同；改变 `model` 即可选择档位。默认单图方式不变；测试档另有两条[视频参考完整规格](#h3-reference-exact)。质量档另有本文末尾的6秒竖屏文字、首帧和首尾帧方式；多图、max和参考音频已按本文“H3新增已验规格”的完整组合开放。
POST`/coinseed/v1/jobs`
| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 必填 | `h3-test` / `h3-custom1` / `h3-quality` |
| `prompt` | string | 必填 | 去除首尾空白后不为空，最多 12000 字符 |
| `asset_tasks` | string[] | 必填 | 恰好 1 个本站本人已完成的图片上传任务号 |
| `seconds` | integer | 建议显式传入 | 4–15 整数；省略时接口默认 5 秒 |
| `orientation` | string | 可选 | `landscape` 横屏，或 `portrait` 竖屏；默认横屏 |
| `seed` | integer | 可选 | 0–9007199254740991；固定 seed 不保证跨次完全一致 |
### 输出与参考精度
固定每单 1 个 MP4、24 FPS。输出名义时长为所选整数秒；帧对齐可能带来少量尾帧，例如选择 4 秒的作品实测约 4.46 秒，仍只按 4 秒计费。
参考图使用固定 `match` 精度：按输出档位的参考尺寸处理。步数、采样器、LoRA及任意宽高仍为固定合同；max和2K/4K接续只开放后文明确列出的完整规格。PNG / JPG / WebP 不设本站文件体积上限；格式和可解码性仍由服务端验证，服务端还会验证文件能否解码为图片。
### 先上传，再生成
POST`/v1/videos`
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/v1/videos' \
-H "Authorization: Bearer $COINSEED_API_KEY" \
-F 'model=coinseed-asset' \
-F 'file=@reference.jpg' \
--output upload.json
```
首次上传响应由网关封装为标准任务回执。先保存 `upload.json` 中的 `id`，并校验 `object: "video"`、`model: "coinseed-asset"` 和小写 `status: "completed"`。这里的 `object: "video"` 是接口封装类型，不表示上传文件是视频；首次 POST 响应不含 `asset_task_id` 或 `kind`。
```json
{
"id": "task_YOUR_UPLOAD_ID",
"object": "video",
"model": "coinseed-asset",
"status": "completed"
}
```
提交 H3 前，建议查询 `GET /v1/videos/{id}`，确认返回的 `kind: "image"`、`asset_task_id` 与保存的 `id` 一致，且任务已完成。若初次回执尚未完成，继续查询原任务，不重复上传。
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/v1/videos/task_YOUR_UPLOAD_ID' \
-H "Authorization: Bearer $COINSEED_API_KEY" \
--output uploaded-asset.json
```
确认是本人已完成的图片上传任务后，把最初保存的 `id` 放进生成请求的 `asset_tasks`。素材不能跨账号使用，也不能使用上游素材 ID 或公网图片 URL 替代。
```json
{
"model": "h3-custom1",
"prompt": "以 为参考，蒸汽缓缓升起，镜头轻微推进，保持主体外观一致",
"seconds": 6,
"orientation": "landscape",
"asset_tasks": [
"task_YOUR_UPLOAD_ID"
]
}
```
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/coinseed/v1/jobs' \
-H "Authorization: Bearer $COINSEED_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @h3-request.json \
--output submitted.json
```
将上面的 JSON 保存为 `h3-request.json`，替换上传任务号后运行。上传素材本身不收生成费；当前首张参考图已包含在基础生成价内。
H3 · H3-TEST
## H3 测试
先用短片验证动作和构图，再决定是否换更高档位。 画质受参考图和提示词影响，更高档位不保证每次都得到更满意的结果。
| 项目 | 规格 |
| --- | --- |
| 模型 ID | `h3-test` |
| 输入 | 一张本人上传的参考图 + 提示词 |
| 分辨率 | 横屏 960 × 544 · 竖屏 544 × 960 |
| 固定档位 | Ref2VA · 4 步 · euler · match 参考精度 |
| 输出 | 一个 MP4，不附加超分 |
| 正式秒价 | **实时目录 `h3-test` 的正式单价** |
| 费用示例 | 4秒 × 实时秒价 · 6秒 × 实时秒价 · 10秒 × 实时秒价 · 15秒 × 实时秒价 |
计费公式：**所选名义输出秒数 × 当前正式秒价**。首张图包含；冷启动与对齐尾帧不加价。完整参数与上传方式见[H3 通用契约](#h3)，查询方式见[异步任务与下载](#lifecycle)。
H3 · H3-CUSTOM1
## H3 加速
在 768P 下平衡细节与生成耗时，适合常规制作。 画质受参考图和提示词影响，更高档位不保证每次都得到更满意的结果。
| 项目 | 规格 |
| --- | --- |
| 模型 ID | `h3-custom1` |
| 输入 | 一张本人上传的参考图 + 提示词 |
| 分辨率 | 横屏 1344 × 768 · 竖屏 768 × 1344 |
| 固定档位 | Ref2VA · 8 步 · er_sde · match 参考精度 |
| 输出 | 一个 MP4，不附加超分 |
| 正式秒价 | **实时目录 `h3-custom1` 的正式单价** |
| 费用示例 | 4秒 × 实时秒价 · 6秒 × 实时秒价 · 10秒 × 实时秒价 · 15秒 × 实时秒价 |
计费公式：**所选名义输出秒数 × 当前正式秒价**。首张图包含；冷启动与对齐尾帧不加价。完整参数与上传方式见[H3 通用契约](#h3)，查询方式见[异步任务与下载](#lifecycle)。
H3 · H3-QUALITY
## H3 质量
使用更多推理步骤，适合对细节有更高要求的作品。 画质受参考图和提示词影响，更高档位不保证每次都得到更满意的结果。
| 项目 | 规格 |
| --- | --- |
| 模型 ID | `h3-quality` |
| 输入 | 一张本人上传的参考图 + 提示词 |
| 分辨率 | 横屏 1344 × 768 · 竖屏 768 × 1344 |
| 固定档位 | Ref2VA · 20 步 · res_multistep · match 参考精度 |
| 输出 | 基础输出一个 MP4；仅单图参考、5秒横屏可选[同工作流接续2K/4K](#video-upscale) |
| 接续超分费 | 2K ¥0.04/实际秒、最低¥0.20；4K ¥0.08/实际秒、最低¥0.40；基础生成费另计 |
| 正式秒价 | **实时目录 `h3-quality` 的正式单价** |
| 费用示例 | 4秒 × 实时秒价 · 6秒 × 实时秒价 · 10秒 × 实时秒价 · 15秒 × 实时秒价 |
计费公式：**所选名义输出秒数 × 当前正式秒价**。首张图包含；冷启动与对齐尾帧不加价。完整参数与上传方式见[H3 通用契约](#h3)，查询方式见[异步任务与下载](#lifecycle)。
COINSEED · ASYNC JOBS
## Omni 视频创作与编辑
兼容旧客户端：`ingredients`＋恰好1张图片，仅当4/6秒、横屏16:9、原生360P/720P，可免费本地放大至1080P且无视频/语音参考时，公开接口按 `frames` 单首帧生成并按原单价计费。该兼容请求使用固定首帧语义；不代表自由素材参考模式已开放。推荐客户端直接发送 `input_mode: frames`。多图及其他组合不转换。
已开放能力（完整参数以实时目录为准）：
| 输入方式 | 时长与方向 | 原生分辨率与交付 | 价格 |
| --- | --- | --- | --- |
| 文字、单首帧、首尾帧、1–3图素材 | 4/6/8/10秒，横屏或竖屏 | 360P/720P，可选local免费普通缩放；720P的4/6/8秒可选Google原生1080P | ¥0.05/秒；Google另加¥0.02/秒、最低¥0.10 |
| 1–3图素材 + 本人的Gemini TTS声音 | 4/6/8/10秒，横屏或竖屏 | 360P/720P，可选local免费普通缩放 | ¥0.05/秒 |
| 编辑本人已生成的视频 | 4/6/8/10秒横竖屏，0–3张有序参考图 | 360P/720P，可免费本地放大至1080P | ¥0.08/秒，包含原片输入费 |
| 编辑上传MP4 | 4秒横屏，不附加图片 | 360P/720P，不超分 | ¥0.32/条，包含原片输入费 |
上传视频编辑支持4/6/8/10秒、横竖屏、0–3张有序参考图、原生360P/720P及免费本地1080P放大；时长与原片一致，包含原片输入费为¥0.08/秒。不能叠加声音引用或 Google 原生超分。
Omni 的接口合同包含文字、单张首帧、首尾帧、1–3 图素材、TTS 语音参考和视频编辑。下文是用法说明，不代表这些组合全部已开放；请先查看实时目录和本节下方的完整规格。输入方式、图片张数、时长、方向、分辨率、超分和是否引用配音/视频源必须同时匹配，不能把不同已通过规格自由拼接。
网页流程：选择 Omni → 选择已开放的输入方式 → 上传或选择本人素材 → 填写动作或修改要求 → 核对完整规格与整单预计金额 → 提交 → 在“我的作品”查看、下载。提交结果未知时保留原任务号查询，不重复提交。
### 选择输入方式
| 用法 | 说明 |
| --- | --- |
| 单张首帧 | 用一张图片确定开始画面；API 使用 `input_mode: frames`，`asset_tasks` 只放一个图片任务号。 |
| 首尾帧 | 第二张图片是结束画面；必须有独立的双帧规格，单首帧成功不代表首尾帧已开放。 |
| 1–3 图素材 | 约束人物、场景或物体，不等同于锁定首尾画面；API 使用 `ingredients`。1、2、3 张图分别属于不同完整规格。 |
| 素材 + TTS | 在素材请求中引用本人已完成的 Gemini TTS 任务；不接受任意外部音频。网页的 voice 模式在 API 中仍为 `ingredients`。 |
| 编辑已有视频 | 选择本人已完成的 已生成视频作为 `source_task`；支持4/6/8/10秒横竖屏、0–3张有序参考图、360P/720P及免费本地1080P放大，时长与原片一致。 |
| 编辑上传 MP4 | 先上传并确认 MP4 视频素材，再用 `reference_video_task` 引用，可另加 0–3 张图片。两种视频源互斥，编辑均不能再附加 `voice_task`。 |
图片为 PNG/JPEG/WebP，不设本站文件体积上限；上传 MP4 不设本站文件体积上限，实际时长应匹配 4/6/8/10 秒之一，误差不超过 0.1 秒。上传后先确认任务成功、素材类型和真实时长/尺寸，再绑定。具体上传与查询见 参考素材章节。
编辑时，网页依据匹配的本人成功任务锁定来源时长与方向，换视频源才能改变；服务端再次验证，不以客户端声明为准。请求仍携带与来源相符的 `seconds` 和 `orientation`。`source_seconds` 只是网页预估字段，禁止把它、源宽高、单价、usage、上游账号/UUID/URL/路径当成 API 授权或计费参数。
### 生成任务安全重试与费用状态
网页与 API 共用同一套后台策略：只有明确未提交或被上游拒绝的临时故障才自动重试，总计最多 3 次，间隔 15 秒、45 秒。同一订单只预占一次费用，重试中不退款、不重复扣费；最终失败退回预占，成功按一次交付结算。
查询 `GET /coinseed-generation/v1/jobs/{task_id}`，读取 `message` 和 `retry`：
| 字段 | 含义 |
|---|---|
| `phase` | `queued` / `processing` / `retry_wait` / `blocked` / `checking` / `failed` / `succeeded` |
| `attempt` / `max_attempts` | 本站尝试次数 / 上限 3；上游内部恢复可能另有尝试 |
| `reason_code` / `category` | 脱敏原因码 / `temporary`、`account`、`input`、`provider`、`delivery`、`unknown` 等 |
| `next_retry_at` / `retry_after_seconds` | 自动重试时间（UTC）/ 剩余秒数，不代表应新建订单 |
| `can_retry` / `action` | 仅终态临时故障允许重新提交；其他按 `wait`、`modify_input`、`retry_later`、`contact_support` 处理 |
| `charge_status` | `reserved` 预占保留 / `settled` 成功结算 / `refunded` 失败已退回 |
提交或生成结果未知（包括只有 HTTP 503、读取超时、连接中断且无法证明未受理）时，`phase=checking`、`can_retry=false`。只查询原任务；**不要重发 POST**。若首次 POST 没拿到任务号，先从本人任务历史核对并联系客服，不能把 503 当作未受理证明。内容拒绝需修改输入；账号或服务问题会显示具体处理提示。历史未知订单不自动加入重试。
`phase=blocked`、`reason_code=COINSEED_ACCOUNT_UNAVAILABLE` 表示上游账号未就绪，任务尚未开始生成。原任务和预占保留，恢复后继续；不要重复提交，长时间未恢复请联系客服。
POST `/coinseed-generation/v1/jobs`
| 参数 | 说明 |
| --- | --- |
| `model` | `omni-flash`，不会替换成 Veo 或其他模型 |
| `prompt` | 非空文字；本站不另设提示词长度上限 |
| `seconds` | 4 / 6 / 8 / 10 整数秒；编辑须匹配服务端确认的来源秒档 |
| `orientation` | `landscape` 或 `portrait`；编辑须匹配服务端确认的来源方向 |
| `input_mode` | `text`、`frames` 或 `ingredients` |
| `asset_tasks` | 文字为空；帧 1–2 张；普通素材 1–3 张；编辑 0–3 张；均为本人已确认完成的图片素材任务 |
| `resolution` | 文字固定 `720p`；非文字可选 `360p` / `720p`，须匹配完整规格 |
| `upscale_mode` | `none`、`local` 或 `google_1080p`；Google原生超分以720P为输入，Omni限4/6/8秒，Veo限8秒；local免费普通缩放 |
| `voice_task` | 素材模式可引用本人已完成的 Gemini TTS 任务；不能与视频编辑叠加 |
| `source_task / reference_video_task` | 本人已完成 已生成视频 / 本人已确认 MP4 上传素材，最多选一种 |
720P 横屏 1280×720、竖屏 720×1280；每单一个 MP4。视频按所选时长交付，后台可能裁剪或重新编码，不宣称所有档位都是模型原生时长。Omni支持原生360P/720P；720P的4/6/8秒组合及Veo Lite/Fast的8秒组合可选Google原生1080P超分。local是免费普通缩放。
### 单张首帧（8秒横竖屏；另有4/6秒横屏及4秒竖屏）
先核对这一整组规格已开放；首尾帧需另加第二张图并重新核对完整规格。
```json
{
"model": "omni-flash",
"prompt": "人物缓缓回头，镜头稳定",
"seconds": 4,
"orientation": "landscape",
"input_mode": "frames",
"asset_tasks": [
"task_YOUR_FIRST_FRAME"
],
"resolution": "720p",
"upscale_mode": "none"
}
```
### 首尾帧
第一张为开始画面，第二张为结束画面。当前开放8秒横屏或竖屏，以及10秒横屏；均为原生360P/720P，可免费本地放大至1080P。
```json
{
"model": "omni-flash",
"prompt": "人物缓缓回头，镜头稳定",
"seconds": 8,
"orientation": "landscape",
"input_mode": "frames",
"asset_tasks": [
"task_YOUR_FIRST_FRAME",
"task_YOUR_LAST_FRAME"
],
"resolution": "720p",
"upscale_mode": "none"
}
```
### 多图素材
8秒横屏或竖屏支持1、2或3张不同素材图；10秒支持竖屏1–3张、横屏3张，并有10秒横屏首尾帧；4秒横屏支持3张。均为原生360P/720P，可免费本地放大至1080P，图片顺序与asset_tasks一致。
```json
{
"model": "omni-flash",
"prompt": "图一人物走进图二场景，拿起图三的物品",
"seconds": 4,
"orientation": "landscape",
"input_mode": "ingredients",
"asset_tasks": [
"task_YOUR_PERSON",
"task_YOUR_SCENE",
"task_YOUR_PROP"
],
"resolution": "720p",
"upscale_mode": "none"
}
```
### 引用已完成 TTS
配音必须是本账号已完成的 Gemini TTS 任务；本例的 1 图 + 配音也需独立开放。
```json
{
"model": "omni-flash",
"prompt": "人物自然说话，使用提供的配音参考",
"seconds": 4,
"orientation": "landscape",
"input_mode": "ingredients",
"asset_tasks": [
"task_YOUR_REFERENCE_IMAGE"
],
"resolution": "720p",
"upscale_mode": "none",
"voice_task": "task_YOUR_COMPLETED_COINSEED_TTS"
}
```
### 编辑本人已生成的 已生成视频
这里假定源视频经服务端确认为 4 秒横屏。若源不同，须使用来源真实秒档、方向及对应已开放规格。
```json
{
"model": "omni-flash",
"prompt": "保留人物动作，将背景改成傍晚海边",
"seconds": 4,
"orientation": "landscape",
"input_mode": "ingredients",
"asset_tasks": [],
"resolution": "720p",
"upscale_mode": "none",
"source_task": "task_YOUR_COMPLETED_COINSEED_VIDEO"
}
```
### 编辑上传 MP4
这里假定上传素材已被确认是 4 秒横屏 MP4。不能同时传 source_task 或 voice_task。
```json
{
"model": "omni-flash",
"prompt": "保留动作，将环境光改成温暖夕阳",
"seconds": 4,
"orientation": "landscape",
"input_mode": "ingredients",
"asset_tasks": [],
"resolution": "720p",
"upscale_mode": "none",
"reference_video_task": "task_YOUR_UPLOADED_MP4"
}
```
### 文字生成
纯文字固定 720P、none，不传任何参考；其他秒档仍以已开放范围为准。
```json
{
"model": "omni-flash",
"prompt": "雨后的城市小巷，镜头缓慢前进",
"seconds": 4,
"orientation": "landscape",
"input_mode": "text",
"asset_tasks": [],
"resolution": "720p",
"upscale_mode": "none"
}
```
### 计费与交付
整单金额 = 输出视频费用 + 编辑输入视频费用（如有）+ Google 1080P 附加费（如有）。普通参考图、首尾帧和最多 3 张素材图包含在基础价内；引用已付费 TTS 不再收费，新建 TTS 按配音模型单独计费。360P 沿用基础价；local 只做免费普通缩放，不作为收费 AI 超分。
以下为当前已确认报价示例，正式单价与开放状态请核对[实时目录](/create/pricing)：
| 服务 | 规则 | 4 秒 | 6 秒 | 8 秒 | 10 秒 |
| --- | --- | ---: | ---: | ---: | ---: |
| 基础生成 | 输出 ¥0.05/秒 | ¥0.20 | ¥0.30 | ¥0.40 | ¥0.50 |
| 视频编辑 | 输出 ¥0.05/秒 + 输入 ¥0.03/秒，输入输出秒档一致 | ¥0.32 | ¥0.48 | ¥0.64 | ¥0.80 |
| Google 1080P 附加费 | 输出 ¥0.02/秒，最低 ¥0.10 | +¥0.10 | +¥0.12 | +¥0.16 | +¥0.20 |
例如 4 秒视频编辑并选择 Google 1080P：¥0.20 输出 + ¥0.12 输入 + ¥0.10 交付 = ¥0.42。新建 Gemini TTS 为 ¥0.01/次、最多 120 个 Unicode 字符；引用已付费配音不重复收费。
输出按所选名义秒档结算；编辑源必须通过服务端实际时长校验，再按匹配秒档计输入费用，少量对齐尾帧不加价。报价示例不表示规格已开放；`price_status: pending`、`open: false` 或未匹配完整规格时不可提交。确定失败按任务规则退款；未知受理状态保留原单核对，查询和重复下载不额外收费。
提交、查询和下载详见 [异步生成流程](#generation-jobs)。
MUSE · VIDEO
## Muse 视频
### Muse 可选来源（普通 API Key）
普通API Key可将可选请求头`X-Coinseed-Provider`设为`muse-laoda`或`muse-laozeng`，在本人既有模型、Key与分组授权范围内选择来源；不携带时仍按当前路由优先级调度。它不新增权限、不改变价格或已开放完整规格，也不保证来源健康、成功率或固定耗时。
该头仅适用于以下三个模型的普通生成POST；不用于素材上传、超分或其他模型。Spark的普通JSON与SSE均可指定来源。视频和图片的GET原任务查询及本人作品下载不受此头影响，无需携带它，也不能用它切换原任务来源。
| 模型 | 生成POST | 可选来源 |
| --- | --- | --- |
| `muse-spark` | `/v1/chat/completions` | `muse-laoda` / `muse-laozeng` |
| `muse-image` | `/coinseed-muse-image/v1/jobs` | `muse-laoda` / `muse-laozeng` |
| `muse-video` | `/coinseed-muse/v1/jobs` | `muse-laoda` / `muse-laozeng` |
显式来源不合法、与模型不匹配、未获授权或不可用时，请读取错误说明；系统不自动改选其他来源，也不自动重发本次显式来源请求。超时、断线、未取得任务号或UNKNOWN不能当作未受理：保留原请求时间、请求编号与已有任务号，先核对原任务和用量，必要时联系客服；禁止换来源再POST或自动重发，不能自行推断退款。Spark不创建异步任务号，按原请求时间、编号和用量核对。
以下HTTP视频例与Python SDK Spark例是独立的生成请求，执行会按原规则计费。只提交选定请求一次；SDK设置`max_retries=0`关闭自动重试。SDK示例的`extra_headers`仅作用于该次调用；不选来源时省略它。视频和图片仍使用上表各自的异步POST，不能把它们的模型ID直接填入`chat.completions.create()`。
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/coinseed-muse/v1/jobs' \
-H "Authorization: Bearer $COINSEED_API_KEY" \
-H 'Content-Type: application/json' \
-H 'X-Coinseed-Provider: muse-laoda' \
--data-raw '{"model":"muse-video","prompt":"雨后的城市小巷，镜头缓慢向前移动","seconds":4,"orientation":"landscape"}'
```
```python
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COINSEED_API_KEY"],
base_url="https://api.coinseed.net/v1",
max_retries=0,
)
reply = client.chat.completions.create(
model="muse-spark",
messages=[{"role": "user", "content": "用一句话描述雨后的城市小巷。"}],
stream=False,
extra_headers={"X-Coinseed-Provider": "muse-laozeng"},
)
print(reply.choices[0].message.content)
```
用文字描述主体、场景、动作与镜头，生成一个视频。图片输入和方形按独立验收状态开放；请先查看[实时目录](/create/pricing)中 `muse-video.input_modes`、`delivery_profile.square` 与 `extended_specs` 的完整组合。未列出的模式不能提交，文档示例不会自动开放能力。
- `text`：文字生成，不传图片。
- `first-frame`：单张首帧，使用 `image` 或 `image_url`。首帧图片在提交前按所选视频画布等比缩放；比例不符时居中补白，保留完整图片，不裁切或拉伸。相同比例沿用原图。生成模型仍可能产生细节变化，不能保证逐像素复现。
- `reference`：主体 / 风格弱参考，使用 `reference_image`；不保证首帧构图、精确保形或人物身份一致。
- 文字 / 首帧横竖屏保留原 4 / 6 / 8 / 10 秒。弱参考、方形还必须匹配 `extended_specs`；模式列表或方形尺寸本身不能开放其他组合。
| 输入方式 | 时长 | 方向与交付尺寸 | 计费 |
| --- | --- | --- | --- |
| 文字 / 单张首帧 | 4 / 6 / 8 / 10 秒 | 横屏1280×720或竖屏720×1280 | ¥0.05/秒 |
| 主体 / 风格弱参考 | **4 / 6 / 8 / 10秒** | **横屏1280×720 / 竖屏720×1280** | ¥0.05/秒，即¥0.20/0.30/0.40/0.50，无传图附加费 |
| 老曾：文字 / 单首帧 / 弱参考方形 | **仅4秒** | **仅方形720×720** | ¥0.20/单，无传图附加费 |
老曾来源的4秒方形已开放文字、首帧和弱参考；方形6/8/10秒尚未开放，网页与API采用相同限制。
网页选择输入方式后，可选择本地图片、预览和移除；切换账号或模型清除待提交图片。图片随生成请求提交，无需第三方图床。资产库旧作品可以先下载，再选择本地文件。
POST`/coinseed-muse/v1/jobs`
| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 必填 | `muse-video` |
| `prompt` | string | 必填 | 非空；本站不另设提示词长度上限 |
| `seconds` | integer | 必填 | 文字/横竖屏首帧为 `4 / 6 / 8 / 10`；弱参考横竖屏同为 `4 / 6 / 8 / 10`；老曾方形三种输入仅 `4`；`duration` 别名不能冲突 |
| `orientation` | string | 可选 | `landscape` / `portrait`，默认横屏；弱参考可选横屏或竖屏，`square` 仅4秒首帧 |
| `size` / `aspect_ratio` | string | 可选 | `16:9` / `9:16` / `1:1`，与方向字段必须一致 |
| `image` / `image_url` | string | 首帧模式必填其一 | 一张 PNG/JPEG/WebP 的内联 data URL |
| `reference_image` | string | 弱参考模式必填 | 一张内联图片，与上面两个字段互斥 |
| `extra` | string | 可选 | 补充提示词；本站不另设长度上限 |
| `resolution` | string | 可选 | 仅 `720p`；不开放原生 1080P 或 AI 超分 |
每单最多一张静态图片，只接受 `data:image/png;base64,...`、`data:image/jpeg;base64,...`、`data:image/webp;base64,...`。原文件不设本站体积上限，每边 64–8192 像素，总像素不超过 3200 万。`image_url` 是字段别名，也不接受任意网络地址。只支持 JSON 内联，不支持直接 multipart。
不开放尾帧、多图、参考视频、视频编辑、数量 `n` 或客户自定 `timeout`。
上游明确返回“未生成媒体、仅返回文字”且未产出视频时，本单确认失败并自动退款，网页/API 会提示修改输入；系统不自动重新生成。超时、断线和结果未知仍保留原单查询，不能当作失败盲目重发。
横屏为 1280 × 720；竖屏为 720 × 1280；已开放的方形为 720 × 720；每单 1 个 MP4。4 / 6 / 8 / 10 秒是**交付时长**，平台会核对原片，必要时裁剪、缩放或重新编码为所选交付规格；这些时长不是模型原生时长保证。原片不足所选时长时，本单按失败处理并退还生成费。不附加 AI 超分。
```json
{
"model": "muse-video",
"prompt": "雨后的城市小巷，镜头缓慢向前移动，柔和电影光影",
"seconds": 6,
"orientation": "landscape"
}
```
首帧在上面的 JSON 增加 `image`（或 `image_url`）；弱参考改用 `reference_image`，`seconds` 可选4/6/8/10，`orientation` 设为landscape或portrait；老曾方形可用文字、image首帧或reference_image弱参考，均设4秒、square。每次只传一个图片字段。下面只是请求体准备，不会提交订单：
```python
import base64
from pathlib import Path
image = "data:image/png;base64," + base64.b64encode(Path("frame.png").read_bytes()).decode()
payload = {"model": "muse-video", "prompt": "人物自然转头，镜头缓慢推进",
"seconds": 4, "orientation": "landscape", "image": image,
"extra": "保持服装和人物外观一致"}
```
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/coinseed-muse/v1/jobs' \
-H "Authorization: Bearer $COINSEED_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @muse-request.json \
--output submitted.json
```
老曾Muse文字视频新增横屏1/2/3/7/9秒，以及4秒3:4、2:3、3:2画幅。按所选时长交付，必要时裁剪原片，不延长或循环；实际交付尺寸可从作品回执读取。
将所选请求 JSON 保存为 `muse-request.json`。正式秒价：**实时目录 `muse-video` 的正式单价**；公式为所选名义输出秒数 × 秒价，与 Omni 采用相同秒价；已开放的图片输入不另加传图费。Muse先按所选名义秒数预占，验证交付媒体达标后结算；不按上游原始视频多出的秒数收费。过短、方向不符或无有效媒体属于交付失败，确定失败按规则退还预占；结果未知保留原单核查。4秒 × 实时秒价，6秒 × 实时秒价，8秒 × 实时秒价，10秒 × 实时秒价。
提交后保存 `task_id`，用 `GET /coinseed-muse/v1/jobs/{task_id}` 查询原任务。成功后读取本站 `/v1/tasks/{task_id}/artifacts`，携带本人 API Key 下载；完整示例见[异步任务、状态与下载](#lifecycle)。查询和重复下载不额外收费。
COINSEED · ASYNC JOBS
## Nano Banana 2.1 图片
**Nano Banana 2.1 和 Pro 均开放五种比例、0–3张有序参考、每单1–4张。** 分别按成功交付张数¥0.10/张、¥0.15/张结算，参考图不另收费。像素以原图为准，不承诺固定尺寸或原生2K/4K。
POST /coinseed-generation/v1/jobs
参考图先按 Coinseed素材上传 取得确认完成的任务号。无参考图时 asset_tasks 为空；使用参考图时最多三个且不能重复。
```json
{
"model": "nano-banana-2.1",
"prompt": "午后咖啡馆，蓝色陶瓷茶壶，写实摄影",
"aspect_ratio": "1:1",
"outputs_per_prompt": 1,
"asset_tasks": []
}
```
```json
{
"model": "nano-banana-2.1",
"prompt": "保持参考人物外观，将场景改为雨后街道",
"aspect_ratio": "9:16",
"outputs_per_prompt": 1,
"asset_tasks": [
"task_YOUR_FIRST_REFERENCE",
"task_YOUR_SECOND_REFERENCE",
"task_YOUR_THIRD_REFERENCE"
]
}
```
批量由后台拆成独立单图任务，每个子任务只提交一次。全部明确结束后，按实际交付张数结算；部分成功只扣成功图片的费用，全失败退整单款。未知提交保持核对，不退款后自动重做。下载成品列表中全部图片，不要只取第一张。查询或重复下载不再收费。
各输入方式、批量与附加交付的正式价格和开放状态，以本站中央 `/create/pricing` 对应模型 `variants` 为准；`price_status: pending` 或 `open: false` 不可提交。
TRANSPARENT BILLING
## 价格、扣费与退款
已确认的原生模型费率见对应章节；当前正式收费与开放状态以 [中央价目表](https://api.coinseed.net/create/pricing) 为准。正式目录版本标识价格与开放规格目录，说明文本修订号标识本页文字修订，两者独立；读取目录的时间不表示目录或文档更新时间。目录仍pending的模型保持关闭，`null` 不是免费。网页与API共用账号余额，Key限额是额外约束。
| 服务 | 结算口径 | 示例（按本次目录） |
| --- | --- | --- |
| H3标准单图 | 名义输出秒数×该档秒价，首张图包含 | 加速6秒：6×¥0.08=¥0.48；质量15秒：¥2.25 |
| H3已开放视频参考 | 基础输出费＋核验输入视频秒数×参考秒价 | 测试4秒＋2秒视频：¥0.20＋¥0.06=¥0.26 |
| Omni / Muse视频 | 所选名义输出秒数×秒价 | 6秒：6×¥0.05=¥0.30 |
| Coinseed图片 | 实际交付张数×张价 | Nano 2.1：¥0.10/成功交付张；五种比例、0–3张参考、每单1–4张 |
| Gemini TTS | 每次计费，输入最多120 Unicode字符 | 1次¥0.01，按实际音频长度不另收费 |
| 独立AI超分 | max(最低单价,核验实际秒数×秒价) | AI1080的362帧÷24×¥0.02，分币舍入后¥0.30 |
| Muse Spark（开放状态见实时目录） | ¥0.01/次成功回复；已开放且获本人账号/Key权限才可提交 | SSE分片不重复计费；usage缺失或为0不表示免费，也不自动开放 |
| MiniMax M3 | 实际非缓存输入、缓存读取、输出token各乘对应费率 | 费率已确认，开放以实时目录为准，不能按“每次对话固定价”试算 |
| MiniMax图片 / 配音 | 验证交付张数 / 供应商实际计费字符 | 费率已确认，开放以实时目录为准；不是按网页输入字数直接扣费 |
异步订单提交时预扣或冻结额度，确认失败退回对应生成费；明确的部分图片交付按成功张数结算，差额退回。未知提交保留原单核对，不自动退款后重做。冷启动、排队、免费查询与重复下载不加生成费；主动重新生成是新订单。
M3和Speech 2.8会先检查并预占保守上限，钱包与有限Key都须足额；预占不是最终收费，成功按真实用量退差。原生同步接口的无效交付会按网关失败处理退回预占；浏览器未收到文件本身不能证明服务器未交付或已退款。详情见对应章节。
异步人民币订单按目录约定整单四舍五入到分；token/字符账务使用网关内部配额精度，页面金额可能经过显示舍入。不要把内部quota当成人民币，也不要由客户端提交价格或usage。
模型已验证交付，但主观画质、动作或风格不满意，不自动等同生成失败。可提供任务号/请求时间联系管理员核对；当前不承诺主观不满意自动退款。本站未承诺固定生成耗时。
COINSEED · ASYNC JOBS
## 参考素材、首尾帧与视频编辑
参考图片和MP4先上传到 coinseed-media-asset ，完成后再用本人任务号引用；上传本身不收生成费。图片最多三张，PNG/JPEG/WebP不设本站文件体积上限；外部MP4不设本站文件体积上限，实际时长须匹配4/6/8/10秒之一（误差≤0.1秒）。不能填上游账号、项目、media UUID、URL或文件路径。
POST /v1/videos
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/v1/videos' \
-H "Authorization: Bearer $COINSEED_API_KEY" \
-F 'model=coinseed-media-asset' \
-F 'file=@reference.jpg' \
--output upload.json
```
保存返回 id ，使用 GET /coinseed-generation/v1/jobs/{id} 核对返回task_id与保存id一致、status为SUCCESS、真实 kind 与 task_id 。MP4将文件改成 file=@clip.mp4 。只有已确认完成、类型匹配且属于本账号的素材可以使用。
- frames ：第一张是首帧；只有双帧完整规格开放时，才可增加第二张尾帧。单首帧和首尾帧须按对应模型完整规格选择，图片数量和方向须匹配。
- ingredients ：1–3张素材图；Omni可使用已完成的本人Gemini TTS作品作为 voice_task 。
- 编辑生成作品： source_task 必须是本人已完成的已生成视频任务。
- 编辑外部MP4： reference_video_task 必须是本人完成的已生成视频上传任务。
两种视频源不能同时使用；编辑必须保持服务端确认的原片时长和方向，可附0–3张参考图，不能与语音参考叠加。来源不匹配时不能靠手填source_seconds或尺寸覆盖校验。每一输入方式、批量、360P和超分都有独立价格与验收门禁；支持参数不代表已开放。
Coinseed素材须使用native查询入口：标准 `GET /v1/videos/{id}` 为OpenAI兼容包装，会省略kind、时长和尺寸，不能用于MP4编辑准备。H3素材查询入口保持不变。
COINSEED · ASYNC JOBS
## Veo 3.1 Lite
原生8秒720P，首帧、首尾帧和1–3图素材均支持横竖屏；可免费本地放大至1080P，¥0.40/条。
参考图片可使用不同方向，由Flow按目标画面裁切。Veo的4/6秒和实时目录未列出的组合继续验收；8秒各素材模式已开放Google原生1080P超分。
精确模型 veo-3.1-lite 。首帧/首尾帧使用 frames ，支持4 / 6 / 8秒、横竖屏。多图素材使用 ingredients 和1–3张参考图，仅支持8秒。
参考图必须是本人已确认完成的Coinseed素材；首帧必选，尾帧可选。生成分辨率720P，交付方式none/local/google_1080p以逐项报价与真实验收状态为准。单首帧、无超分的4/6/8秒交付会校验原生时长证据，不用裁剪结果冒充该规格。上游报价和账号暂不可用时任务保持安全拒绝或核对，不能自动回退到Omni。
```json
{
"model": "veo-3.1-lite",
"prompt": "以首帧人物为主体，自然转头，镜头稳定",
"seconds": 8,
"orientation": "landscape",
"input_mode": "frames",
"asset_tasks": [
"task_YOUR_FIRST_FRAME"
],
"resolution": "720p",
"upscale_mode": "none"
}
```
各输入方式、批量与附加交付的正式价格和开放状态，以本站中央 `/create/pricing` 对应模型 `variants` 为准；`price_status: pending` 或 `open: false` 不可提交。
COINSEED · ASYNC JOBS
## Veo 3.1 Fast
原生8秒720P，首帧、首尾帧和1–3图素材均支持横竖屏；可免费本地放大至1080P，¥0.64/条。
参考图片可使用不同方向，由Flow按目标画面裁切。Veo的4/6秒和实时目录未列出的组合继续验收；8秒各素材模式已开放Google原生1080P超分。
精确模型 veo-3.1-fast 。首帧/首尾帧使用 frames ，支持4 / 6 / 8秒、横竖屏。多图素材使用 ingredients 和1–3张参考图，仅支持8秒。
参考图必须是本人已确认完成的Coinseed素材；首帧必选，尾帧可选。生成分辨率720P，交付方式none/local/google_1080p以逐项报价与真实验收状态为准。单首帧、无超分的4/6/8秒交付会校验原生时长证据，不用裁剪结果冒充该规格。上游报价和账号暂不可用时任务保持安全拒绝或核对，不能自动回退到Omni。
```json
{
"model": "veo-3.1-fast",
"prompt": "以首帧人物为主体，自然转头，镜头稳定",
"seconds": 8,
"orientation": "landscape",
"input_mode": "frames",
"asset_tasks": [
"task_YOUR_FIRST_FRAME"
],
"resolution": "720p",
"upscale_mode": "none"
}
```
各输入方式、批量与附加交付的正式价格和开放状态，以本站中央 `/create/pricing` 对应模型 `variants` 为准；`price_status: pending` 或 `open: false` 不可提交。
COINSEED · ASYNC JOBS
## Veo 3.1 低优先级
**当前已报价但未开放。以下是接入合同，不是可直接下单的规格。**
精确模型 veo-3.1-lite-low-priority 。首帧/首尾帧使用 frames ，支持4秒、横竖屏。当前低优先级只支持4秒帧模式，不接受素材模式。
参考图必须是本人已确认完成的Coinseed素材；首帧必选，尾帧可选。当前仅提供4秒帧模式；生成分辨率720P，交付方式none/local/google_1080p以逐项报价与真实验收状态为准。Low不承诺Lite/Fast单首帧4/6/8秒规格的原生时长证明。上游报价和账号暂不可用时任务保持安全拒绝或核对，不能自动回退到Omni。
```json
{
"model": "veo-3.1-lite-low-priority",
"prompt": "以首帧人物为主体，自然转头，镜头稳定",
"seconds": 4,
"orientation": "landscape",
"input_mode": "frames",
"asset_tasks": [
"task_YOUR_FIRST_FRAME"
],
"resolution": "720p",
"upscale_mode": "none"
}
```
各输入方式、批量与附加交付的正式价格和开放状态，以本站中央 `/create/pricing` 对应模型 `variants` 为准；`price_status: pending` 或 `open: false` 不可提交。
COINSEED · ASYNC JOBS
## Nano Banana Pro 图片
当前已开放：五种比例，纯文字或1–3张有序参考图，每单1–4张，¥0.15/成功交付张。
**Nano Banana Pro已开放五种比例、0–3张有序参考、每单1–4张。** model 必须为 `nano-banana-pro`，价格与权限独立管理。以下合同或示例只有实时目录列出的完整组合才能提交，按实时目录选择完整组合。
```json
{
"model": "nano-banana-pro",
"prompt": "精致陶瓷产品摄影",
"aspect_ratio": "16:9",
"outputs_per_prompt": 1,
"asset_tasks": []
}
```
各输入方式、批量与附加交付的正式价格和开放状态，以本站中央 `/create/pricing` 对应模型 `variants` 为准；`price_status: pending` 或 `open: false` 不可提交。
完整参数和部分成功结算规则见 Nano通用说明 。
COINSEED · ASYNC JOBS
## Gemini TTS 配音
精确模型 gemini-tts 。去除首尾空白后输入1–120个Unicode字符；emoji按Unicode码点计数。选择30种系统音色之一，Speaker名称1–64字符，语气说明最多500字符。交付24kHz单声道PCM WAV，可在网页播放与下载。
POST /coinseed-generation/v1/jobs
```json
{
"model": "gemini-tts",
"input": "欢迎来到Coinseed，开始你的创作。",
"voice": "Kore",
"voice_name": "Speaker",
"instructions": "温和自然，正常语速"
}
```
本模型使用异步任务接口，不能用 `/v1/audio/speech` 调用 `gemini-tts`；该同步路径属于下文独立的 MiniMax 原生配音。实际音频时长受文字与语速影响；所选音色、Speaker与语气是请求参数，不承诺固定秒数。
各输入方式、批量与附加交付的正式价格和开放状态，以本站中央 `/create/pricing` 对应模型 `variants` 为准；`price_status: pending` 或 `open: false` 不可提交。
### 系统音色
以下30种是当前配置允许的系统音色，不表示每个音色都逐一完成了独立真实样本验收。已验收的Kore示例不构成其他音色的效果保证。
Achernar, Achird, Algenib, Algieba, Alnilam, Aoede, Autonoe, Callirrhoe, Charon, Despina, Enceladus, Erinome, Fenrir, Gacrux, Iapetus, Kore, Laomedeia, Leda, Orus, Puck, Pulcherrima, Rasalgethi, Sadachbia, Sadaltager, Schedar, Sulafat, Umbriel, Vindemiatrix, Zephyr, Zubenelgenubi
已完成TTS作品可作为Omni素材视频的 voice_task ，仅允许本人作品；上游媒体与账号由后台解析，不接受客户端UUID、URL或路径。
COINSEED · ASYNC JOBS
## 生成任务提交、查询与作品下载
所有Coinseed生图、生视频、TTS都使用同一异步提交与查询流程；保存原任务号，不能因为超时重发生成POST。接口返回元数据支持不等于该规格已开放，最终以实时规格表、账号和Key权限为准。
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/coinseed-generation/v1/jobs' \
-H "Authorization: Bearer $COINSEED_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @media-request.json \
--output submitted.json
```
保存返回的 task_id ，轮询 GET /coinseed-generation/v1/jobs/{task_id} 直到 SUCCESS 或明确 FAILURE 。 UNKNOWN 或需要核对的状态不要重做。成功后读取 GET /v1/tasks/{task_id}/artifacts ，下载本人任务返回的每个 content_url 。图片可能多张，TTS为audio/WAV，视频为video/MP4；以实际返回的MIME类型与文件名保存。
API下载携带本人API Key，网页登录使用本人会话和同源授权地址。不要把含临时授权参数的作品地址当作公共分享链接。确定失败退费，重复查询和下载不额外扣费；部分图片成功按已交付数量结算。
API BASICS
## API 接入：鉴权与模型列表
BASE`https://api.coinseed.net`
使用HTTPS和你自己的API Key。按模型选择接口，不能把所有模型都接到一个异步入口：
| 模型 / 类型 | POST提交入口 | 回执 / 查询 |
| --- | --- | --- |
| H3三档 | `/coinseed/v1/jobs` | `task_id`，同前缀GET原任务 |
| H3固定Turbo / Sage / 轻量 / 细节 | `/coinseed-h3-presets/v1/jobs` | `task_id`，同前缀GET原任务；专属素材 |
| Omni / Veo / Nano / Gemini TTS | `/coinseed-generation/v1/jobs` | `task_id`，同前缀GET原任务 |
| Muse视频 | `/coinseed-muse/v1/jobs` | `task_id`，同前缀GET原任务 |
| 本机AI1080 | `/coinseed-ai1080/v1/jobs` | `task_id`，同前缀GET原任务 |
| 2K/4K AI超分（已开放） | `/coinseed-upscale/v1/jobs` | 同前缀GET；需专属素材 |
| Muse图片（以实时目录为准） | `/coinseed-muse-image/v1/jobs` | 同前缀GET；非同步images接口 |
| Muse Spark / M3（分别核对开放状态） | `/v1/chat/completions` | JSON或SSE，无本站异步task |
| MiniMax图片（以目录开放为准） | `/v1/images/generations` | JSON `data[0].b64_json`，无异步task |
| MiniMax配音（以目录开放为准） | `/v1/audio/speech` | MP3二进制，无异步task |
| Suno音乐 / WAV转换 | `/coinseed-music/v1/jobs` | `task_id`，同前缀GET原任务；artifacts下载 |
```bash
# 在本机或服务端设置；不要把真实 Key 提交到公开仓库
export COINSEED_API_KEY='YOUR_API_KEY'
```
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/v1/models' \
-H "Authorization: Bearer $COINSEED_API_KEY"
```
模型列表按账号和 Key 权限返回，其中 `coinseed-asset` 等是素材上传模型。可生成模型还需中央目录处于开放状态。Coinseed和Muse图片任务不能用同步 `images.generate()` 替代；MiniMax原生图片使用独立的同步图片接口，须按实时目录核对是否开放。模型列表出现条目也不等于该完整规格已开放。
### 基本约定
- JSON 请求携带 `Content-Type: application/json`；上传使用 multipart，交给客户端生成 Content-Type 边界。
- 精确填写模型 ID 和枚举值。不要传本文参数表之外的宽高、步数、推理预算、回调地址等参数。
- 轮询使用 GET。建议每 5–10 秒一次，根据业务需要设置轮询超时。
- 本版不提供公开 Webhook 契约，也不承诺客户端 `Idempotency-Key` 能替重复提交去重。
- 标准 HTTP 客户端可直接调用公开目录、生成API和余额接口，无需伪装浏览器 User-Agent。若收到403，请记录时间、路径、客户端版本和CF-Ray并联系客服；不要修改请求头掩盖问题，也不要重复POST生成。登录注册页适用独立的网页访问规则。
SUBMIT → POLL → DOWNLOAD
## 异步任务、状态与下载
本节只适用于H3、Coinseed、Muse视频和独立超分等任务接口。对话与MiniMax原生图片/配音不返回这里的task_id，也不使用artifacts下载。
**01****提交一次**保存返回的 task_id
→**02****查询原任务**轮询直到成功或失败
→**03****下载作品**使用本人 Key 取回成品
H3 视频及独立超分任务会按实际记录显示准备、核对、生成和交付进度。启动时的“总等待”“恢复等待”“实际安装”分别展示；没有真实安装记录时显示“未观察到”，不会用总等待代替安装耗时。阶段可能并行，不能把各阶段时间相加；这些时间不作为计费秒数。
显示“系统核对”或“需联系支持”时，请保留原任务编号，勿重复提交。启动阶段受阻不代表媒体任务已取消，也不表示可以重试。
### 提交回执
响应示例仅展示结构，不代表已完成。不要把“取得任务号”当作“已出片”。
```json
{
"task_id": "task_YOUR_TASK_ID",
"status": "QUEUED",
"progress": "0%",
"artifacts_url": "/v1/tasks/task_YOUR_TASK_ID/artifacts"
}
```
GET`/coinseed/v1/jobs/{task_id}`
GET`/coinseed-generation/v1/jobs/{task_id}`
GET`/coinseed-muse/v1/jobs/{task_id}`
GET `/coinseed-ai1080/v1/jobs/{task_id}`
其他已开放异步服务按上表对应前缀查询。
```
# H3 查询入口；Omni / Nano 改成 coinseed-generation；Muse 改成 coinseed-muse
curl --fail-with-body --silent --show-error 'https://api.coinseed.net/coinseed/v1/jobs/task_YOUR_TASK_ID' -H "Authorization: Bearer $COINSEED_API_KEY"
```
| status | 含义 | 客户端操作 |
| --- | --- | --- |
| `NOT_START / SUBMITTED / QUEUED` | 等待或排队 | 继续查询同一任务 |
| `IN_PROGRESS` | 生成、交付或后台核对中 | 继续查询；有核对提示时保留任务号 |
| `SUCCESS` | 已生成且结果可交付 | 读取 artifacts 后下载 |
| `FAILURE` | 确认失败 | 核对整单退款记录；再次生成是新单 |
| `UNKNOWN` | 状态无法确认 | 停止自动提交，联系管理员 |
### 获取成品列表
GET`/v1/tasks/{task_id}/artifacts`
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/v1/tasks/task_YOUR_TASK_ID/artifacts' \
-H "Authorization: Bearer $COINSEED_API_KEY"
```
```json
{
"task_id": "task_YOUR_TASK_ID",
"artifacts": [
{
"key": "video",
"type": "video",
"mime_type": "video/mp4",
"content_url": "/v1/tasks/task_YOUR_TASK_ID/artifacts/video/content"
}
]
}
```
H3 / Omni / Muse 视频常用 key 为 `video`，Nano 图片常用 key 为 `result-0`；以本人任务返回的成品列表为准。完成前成品列表可能为空或返回未就绪，不要重新生成。
GET`/v1/tasks/{task_id}/artifacts/{key}/content`
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/v1/tasks/task_YOUR_TASK_ID/artifacts/video/content' \
-H "Authorization: Bearer $COINSEED_API_KEY" \
--dump-header download.headers \
--output video.mp4
```
下载接口也携带本人 API Key，支持 HEAD；视频支持 Range。API 下载不需要把 Key 放进 URL。网页使用有授权的同源成品地址，不要把临时授权链接公开分享。
完成后及时下载到自己的存储。当前不承诺作品永久保存；素材和作品的保留期限以平台后续公告为准。平台不支持用其他用户的任务号下载作品。
PYTHON · ONE ORDER
## Python 完整示例
下面示例用 `requests` 提交一张 Nano 图片、保存任务号、轮询和下载。需要已开通的账号、足够余额和个人 API Key。只读重查可以由你的业务系统恢复；生成 POST 不自动重试。
```bash
python -m pip install requests
```
```python
import os
from pathlib import Path
import time
import requests
BASE = "https://api.coinseed.net"
session = requests.Session()
session.headers.update({
"Authorization": "Bearer " + os.environ["COINSEED_API_KEY"],
"User-Agent": "coinseed-client-example/1.0",
})
# 只提交一次，不对 POST 使用自动重试。
try:
response = session.post(BASE + "/coinseed-generation/v1/jobs", json={
"model": "nano-banana-2.1",
"prompt": "午后咖啡馆，蓝色陶瓷茶壶，写实摄影",
}, timeout=(15, 120))
except requests.RequestException as exc:
raise RuntimeError("提交结果未知：先核对本站任务记录，勿盲目重发") from exc
Path("submitted-response.json").write_text(response.text, encoding="utf-8")
if response.status_code >= 500 or response.status_code == 408:
raise RuntimeError("已保存响应；提交结果待核对，勿盲目重发")
response.raise_for_status()
created = response.json()
task_id = created.get("task_id")
if not task_id:
raise RuntimeError("未收到可靠任务号；保留响应并联系管理员")
print("任务号：", task_id)
# 客户端超时只停止等待，不会取消或判定服务端任务失败。
deadline = time.monotonic() + 30 * 60
while time.monotonic() < deadline:
response = session.get(
BASE + "/coinseed-generation/v1/jobs/" + task_id, timeout=(15, 60))
response.raise_for_status()
task = response.json()
status = task.get("status")
print(status, task.get("progress"))
if status == "SUCCESS":
break
if status == "FAILURE":
raise RuntimeError("任务确认失败，请核对退款记录")
if status == "UNKNOWN":
raise RuntimeError("任务待核对；保留任务号并联系管理员")
time.sleep(8)
else:
raise TimeoutError("停止轮询；任务可能仍在执行，稍后查询原任务号")
response = session.get(
BASE + "/v1/tasks/" + task_id + "/artifacts", timeout=(15, 60))
response.raise_for_status()
items = response.json().get("artifacts", [])
if not items:
raise RuntimeError("成品尚未就绪；稍后查询原任务，不重新生成")
artifact = items[0]
url = artifact.get("content_url", "")
expected_prefix = "/v1/tasks/" + task_id + "/artifacts/"
if not url.startswith(expected_prefix) or not url.endswith("/content"):
raise RuntimeError("成品地址不符合本站同源路径，请核对响应")
with session.get(BASE + url, stream=True, timeout=(15, 120),
allow_redirects=False) as response:
response.raise_for_status()
if 300 <= response.status_code < 400:
raise RuntimeError("下载发生重定向，请先核对；不把 Key 发往其他站点")
mime = response.headers.get("Content-Type", "").split(";")[0].strip()
suffix = {"image/jpeg": ".jpg", "image/png": ".png",
"image/webp": ".webp", "video/mp4": ".mp4"}.get(mime, ".bin")
output = Path(task_id + suffix)
with output.open("wb") as file:
for chunk in response.iter_content(1024 * 1024):
if chunk:
file.write(chunk)
print("已保存：", output)
```
改用 Omni 时，把请求 JSON 换成[Omni 示例](#omni)并保留查询路径。改用 Muse 时，使用[Muse 示例](#muse)，创建与查询路径均切换为 `/coinseed-muse/v1/jobs`。改用 H3 时，先上传参考图，再用 H3 JSON，同时把创建与查询路径切换为 `/coinseed/v1/jobs`。
WHEN SOMETHING FAILS
## 错误处理与售后
错误响应可能来自账号网关、任务插件或网站入口。先看 HTTP 状态和响应正文；不要只按中文提示文字写业务判断。以下为常见排查方向，具体业务错误码以实际响应为准。
| 情况 | 常见原因 | 处理方法 |
| --- | --- | --- |
| `400 / 422` 参数错误 | 模型 ID、时长、未知字段、参考图数量或素材任务不符合契约 | 按对应模型参数表修正；确认原请求明确拒绝后再提交 |
| `401` 鉴权失败 | Key 缺失、错误、过期 | 检查 Authorization 和 Key 状态 |
| `403` 权限、额度或入口限制 | 账号 / Key 无权限、钱包或Key限额不足、IP限制或入口检查 | 核对模型白名单与客户端；保留原响应 |
| 余额 / Key 额度不足 | 账号余额不足，或 Key 自己的上限已用完 | 钱包充值或调整自己的 Key 设置 |
| `404` 任务或成品不存在 | 任务号、key 不对，或不属于本人 | 检查原回执与成品列表 |
| `409` 成品未就绪 | 任务尚未完成 | 继续 GET 查询原任务 |
| `429` 频率限制 / 队列繁忙 | 请求过于密集、当前容量不足 | 降低轮询频率；遵守响应等待提示，勿循环 POST |
| `408 / 5xx` 或网络断线 | 提交结果可能未知 | 先查本站任务记录；不要盲目重复生成 |
| `FAILURE` | 确认生成失败 | 核对本单费用已退回；无退款时带任务号联系管理员 |
### 联系管理员时提供这些信息
本站用户名或用户ID、模型ID、提交时间、报错截图和必要请求参数。异步任务提供task_id与所选规格；同步/对话无task_id时提供响应request ID（如有）、用量记录和时间，勿伪造任务号。充值问题补充闲鱼订单号与金额。请遮住密码、验证码、API Key 和临时授权下载地址。
**提交结果不确定时**未收到响应不等于未受理。保存响应、任务号和提交时间；异步服务先核对“我的作品”与任务日志；同步/对话先核对用量记录与请求时间。仅在请求明确拒绝，或管理员确认未受理后，才重新提交。
AVAILABILITY · ACCEPTANCE
## 开放状态与待验收项目
列出价格、参数或私有测试结果不代表当前可以提交。以下逐项说明已确认报价与验收条件；已完成验收的模型以实时目录开放状态为准，未完成的保持关闭。不要把接入示例当成已开放授权。
| 服务 | 计划规格 | 目录中的报价 | 当前说明 |
| --- | --- | --- | --- |
| H3目录外组合 | 未列出的素材数量、时长、方向、尺寸或叠加方式 | 查看中央正式目录 | 已验音频、多图/max、固定档与接续超分见后文；其他组合保持关闭 |
| Veo与Nano待验组合 | 低优先级、视频编辑、声音引用及实时目录未列出的完整组合 | 已有正式报价 | Lite/Fast的8秒双帧及多图素材已按实时规格表开放；Nano 2.1/Pro均支持0–3张参考、每单1–4张 |
| Coinseed扩展输入 | Omni首尾帧、素材、配音、视频编辑及附加交付；Nano参考/批量 | 已有相应报价 | 不能由文字/单张规格推断开放 |
| M3、MiniMax原生图片/配音 | 首批受保护规格 | 费率已确认，见下文 | 已验长输入、文件、M3图片理解及MiniMax媒体见各章；额外能力仍须独立验收 |
| Muse Spark | 普通JSON / SSE文字对话 | ¥0.01/次成功回复 | 开放状态以上方实时目录为准；已开放且获本人账号/Key权限才可提交 |
Qwen Image暂未公开；H3 Turbo / Sage / 轻量 / 细节已按固定规格开放，见H3新增已验规格，不能替代用户指定模型。Gemini TTS和Nano批量按对应实时规格表开放；自由工作流参数与公开Webhook暂不提供。
FAQ
## 常见问题
### 注册后为什么不能生成？
新账号余额为零，且尚未开通客户模型权限。请把用户名或用户 ID 发给管理员，核实充值与开通；再重新登录。API Key 的模型白名单也要包含对应模型。
### H3 加速就是之前的 Turbo 吗？
不是同一个模型 ID。正式加速档为 `h3-custom1`，固定 768P、8 步；`h3-turbo` 是另一个已验固定6秒竖屏档，使用专用素材和固定档接口，不能互换模型ID。
### 怎么控制视频横竖屏？
H3和已生成视频用 `orientation: "landscape"` 或 `"portrait"`；老曾Muse另有文字、首帧或弱参考4秒方形的限定组合，不能任意交叉组合。Nano用 `aspect_ratio`，当前2.1开放16:9 / 4:3 / 1:1 / 3:4 / 9:16；两个Nano模型均支持纯文字或1–3张有序参考、每单1–4张；不能传orientation代替。
### 可以把参考图 URL 直接传进去吗？
H3 需要先上传到本站，保存首次回执的 `id`，查询并确认它是已完成图片任务后，把该 `id` 放入 `asset_tasks`。不接受公网 URL、上游 asset ID 或其他账号的任务号替代。
### 4 秒的视频为什么长一点？会多收钱吗？
H3 会按模型帧数对齐，成片可能带少量尾帧。按你选择的 4 秒计费，尾帧不另收费用。Omni 和 Muse 按所选名义输出时长计费；Muse须先校验交付媒体达到所选时长，过长可裁剪，过短或方向不符按交付失败处理，不按上游原片时长额外收费。
### 关闭网页后任务会停吗？
异步任务已受理后，关网页不会取消；可在“我的作品”或用原任务号查询。原生同步/对话同样不保证停止执行，但没有异步历史可恢复；刷新会丢本页临时结果，先下载保存，结果未知时查用量而非重复提交。
### 一次能生成多张图片或多段视频吗？
Nano 2.1与Pro均开放五种比例，纯文字或1–3张有序参考，每单1–4张。视频和Gemini TTS每单一个作品；原生MiniMax图片固定n=1，对话固定n=1，配音每请求一个MP3。批量参数不能绕过当前目录。
### 下载链接能直接发给别人吗？
任务和成品属于对应账号。API 下载需本人 Key；网页临时授权链接也可能包含访问凭据。请下载到本地后，再分享文件；不要公开 Key 或临时链接。
### 能把作品一直放在平台吗？
异步作品也不承诺永久保存。原生同步媒体最多保留本页5份临时文件，对话只保留本页；刷新、关闭或换账号会丢失临时结果，请及时下载。
### API 生成等待时间固定吗？
不固定，受模型、时长、排队和上游状态影响。时长越长，计算时间不一定按比例增加。费用按正式报价与所选规格计算，不按等待时间收费。
## Muse 图片与单图编辑
可用可选请求头选择已授权来源，见[Muse可选来源](#muse-provider)；图片仍使用本节异步接口，模型权限、规格与价格不变。
**售价已确认：¥0.10/合格交付张，单图编辑不另加价。开放以实时目录、完整规格和本人账号/Key权限为准；`open:false` 时不能提交。** 模型 `muse-image`。`POST /coinseed-muse-image/v1/jobs` 创建，`GET /coinseed-muse-image/v1/jobs/{task_id}` 查询，本人账号从 `/v1/tasks/{task_id}/artifacts` 取得下载入口。文字生图和单图编辑均支持1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 2:3 / 3:2，每单1张原图。2:3与3:2的文字生图和单图编辑均已通过普通用户原图下载和计费验收，实测分别为1280×1920、1920×1280；原生像素仍以实际交付为准。比例按实际交付核验，不保证固定像素尺寸或2K。
```json
{"model":"muse-image","prompt":"白色背景上的红色陶瓷杯","n":1,"aspect_ratio":"1:1"}
```
单图编辑加入 `image: "data:image/png;base64,..."`。仅单张静态PNG/JPEG/WebP，每边64–8192、最多3200万像素，提示词1–4000字。禁止远程URL、其他任务引用、multipart、多图、mask、自定分辨率和客户端price/usage。开放模式还须匹配目录的完整 `available_specs` 和本账号 `muse-image` 权限。内联文件不需要Coinseed素材任务，其他服务的素材上传权限规则保持原样。
提交一单先预扣 ¥0.10；成功只收实际验证并交付的1张，不按排队或生成耗时加价。明确失败且不能交付时退还本单冻结费用；未知状态保留原任务和冻结额，先查原编号，不自动重发。查询、HEAD、Range及重复下载不新增生成费。网页和API共用Coinseed余额，任务及附件只允许本人账号读取；旧的受限Key不会自动获得新增模型权限，需要明确允许 `muse-image`。
网页选择“Muse 图片”后选择文字生图或编辑一张图片，再选择已开放比例；编辑直接选择本地图片，无须创建其他模型的素材任务。提交后保存任务号，在“我的作品”中查询并下载原图。再次生成或重新编辑属于新单，再计 ¥0.10。图片、Muse视频和Muse Spark分别控制权限；Spark支持Chat Completions和原生Responses，均按完整文字回复计费。
## H3 单视频与图加视频（以实时完整规格开放为准）
使用现有 `/coinseed/v1/jobs`，三档模型不变。上传图片/视频使用 `POST /v1/videos` 的 `model=coinseed-asset` multipart；读取 `/v1/videos/{id}` 后仅引用本账号 completed 的素材任务号。
```json
{"model":"h3-test","prompt":"参考图中人物，复现视频中的行走动作","seconds":4,"orientation":"landscape","asset_tasks":["task_MY_IMAGE_UPLOAD","task_MY_VIDEO_UPLOAD"]}
```
首轮仅在实时目录 `h3-test.reference_specs` 明确列出时开放下列两种完整组合：
| 输入 | 已核验参考视频 | 输出 | 费用 |
| --- | --- | --- | --- |
| 1 段视频 | 768 × 1344、48 帧、24 FPS、2 秒 | 测试档 4 秒横屏，960 × 544 | 4 × ¥0.05 + 2 × ¥0.03 = **¥0.26** |
| 1 张参考图 + 1 段视频 | 同上；首张图片包含 | 同上 | **¥0.26** |
这些是逐项完整规格，不能拆开交叉组合。提交前核对 `reference_media.width/height/frames/fps`；2 秒但尺寸、帧数或方向不匹配也不能提交。输出 5–15 秒、输出竖屏、其他视频尺寸/帧数、加速/质量档视频参考、两张图片、参考音频、引用原片声音及附加超分不随本段这两条旧规格开放；新增组合见下方H3新增已验规格。输入视频可以自带音轨，但这两条只使用画面，不把原声作为生成参考；不承诺输出静音。
参考视频用于引导环境与运动，不保证保留某个人物、机器人或主体，也不是逐帧编辑服务。样本中图加视频保留了主要人物与机器人；只有视频时主要保留森林环境，主体保真有限。先用短片判断效果。
单视频只保留视频任务号；标准最多一图加一视频。音频/原片音轨新增组合见下方H3新增已验规格；参考组合叠加超分未开放；视频参考方式不叠加FL2VA；质量档的独立文字/首帧/首尾帧方式见本文末尾。多图/max新增组合见下方H3新增已验规格。
输入视频费用 = `ceil(reference_media.frames / 24) × addons.reference_second_cny`。输出费用仍按名义秒数；后台合同上限为2–15个计费秒且不超过输出时长；**当前公开仅前表核验2秒的两条组合**，不接受任意2–15秒参考。后端只信任上传时验证的规范化文件SHA、帧数、24fps与账号归属，不接收客户报价字段。图片包含；素材旧回执缺少 `coinseed.h3.reference-media.v1` 时重新上传原件。
H3测试/加速/质量的现有参考视频秒价分别为¥0.03/¥0.15/¥0.40；以实时目录为准。`reference_specs`逐项限定模型、输出秒数/方向、参考图片数量、视频帧数/尺寸和交付方式，缺失或空列表保持关闭；一条验收不代表其他组合开放。未确认音频费用不按0元受理。
## Muse 新增方式的完整规格限制（补充）
已发布的文字、首帧横竖屏及4/6/8/10秒仍沿用既有方式。新增弱参考与方形不按全局开关交叉组合；目录 `extended_specs` 是独立逐组合门禁，缺失/空数组默认不开放。弱参考已提供 `reference+4/6/8/10秒+landscape或portrait+720p` 八条规格；老曾方形提供 `text/first-frame/reference+4秒+square+720p`，实际可提交范围以实时目录为准。其他组合仍关闭，不因单个输入模式开放而推断可用。
弱参考用 `reference_image`；首帧（含方形）用 `image`（或image_url别名）内联PNG/JPEG/WebP，互斥。不新增1080P、无图片附加费，保持¥0.05/秒。网页切换方式会同步可用时长与方向；API直接传未验收组合会在上游提交前拒绝。旧unknown弱参考单保留原单核对，不属于新单验证。
## 本机 1080P AI 超分（四条完整规格已开放）
本次目录已开放下列四条完整输入规格，仍需账号和Key同时有生成与 `coinseed-ai1080-asset` 上传权限；新增组合不会因模型名已开放而自动可用。收费为核验实际时长 × ¥0.02，每单最低 ¥0.10、整单四舍五入到分。不同于 Coinseed 免费普通放大和 独立2K/4K AI超分服务。
1. `POST /v1/videos`，multipart：`model=coinseed-ai1080-asset` 和一个 `file`。核验上传不收超分费。
2. 保存返回的 `id`，GET `/coinseed-ai1080/v1/jobs/{id}` 确认 `SUCCESS` 和实际帧数；只能用本人在本平台上传的素材，不直接引用 其他模型的 task ID。
3. `POST /coinseed-ai1080/v1/jobs`：`{"model":"coinseed-upscale-1080p","asset_tasks":["task_本人上传ID"]}`。不要传时长、价格、usage、外部 URL 或其他模型参数。
4. 查询同一路径的原任务，成功后用 `/v1/tasks/{task_id}/artifacts` 和本人认证 content 路径下载，支持 HEAD/Range。查询与重复下载免费。
仅实时目录 `accepted_input_specs` 列出的完整输入可提交，均为恒定24fps的H.264 8bit MP4、**一条AAC音轨**：
| 输入尺寸 | 帧数 / 实际秒数 | 输出尺寸 | 整单费用 |
|---|---|---|---|
| 768×1344 | 24帧 / 1秒 | 1080×1890 | ¥0.10 |
| 720×1280 | 96帧 / 4秒 | 1080×1920 | ¥0.10 |
| 720×1280 | 360帧 / 15秒 | 1080×1920 | ¥0.30 |
| 768×1344 | 362帧 / 约15.0833秒（H3原片） | 1080×1890 | ¥0.30 |
其他帧数、横屏、尺寸或无音轨输入暂未开放。H3的768×1344、24fps、362帧且带AAC的原片可直接上传，不需要裁剪尾帧。超分按实际362÷24秒×¥0.02计价，整单四舍五入为¥0.30；这与H3生成按所选15秒收费是两种服务的计费依据。不会自动裁剪、插帧、转帧率或补音轨；禁止旋转、其他流及已达1080P的无效放大。服务端核验原片SHA、帧数、尺寸和音轨后才冻结费用；明确拒绝的未开放规格不收超分费。完成后再次核验学习引擎、原帧数、方向、AAC payload、成片SHA和完整解码。
AI处理保留内容与构图，当前样本的边缘改善偏温和、纹理略平滑，可能出现细节伪影；不保证巨大清晰度提升。与免费CPU普通1080P放大分开，后者只调整像素尺寸。逐帧计算并可能排队，视频时长不是等待时间；4秒/15秒样本曾约59/137秒首次查询到成功（含网络和轮询，非SLA）。费用按交付视频秒数计算，不按处理耗时。
本项1080P超分明确失败且未交付时，只退回该笔超分预占费用，不退回此前已成功交付的基础生成费；未知提交或结果核对中保留原单与该笔预占费用，不自动退款、重发或换账号。网页切换到另一超分平台时需重新核验素材。收到完整签名下载链接即得到其授权，请分享下载后的文件，勿转发签名或API Key。
## 对话：Muse Spark 与 MiniMax M3（价格已确认，开放状态分别核对）
仅`muse-spark`支持本节的[Muse可选来源请求头](#muse-provider)，Python SDK使用`extra_headers`；`MiniMax-M3`不使用该头。
模型 ID 为 `muse-spark` 与 `MiniMax-M3`，区分大小写。使用同一 Coinseed 账号和本人模型受限Key，接口都是 `POST /v1/chat/completions`。普通回复返回JSON，流式回复返回SSE；不创建异步视频任务号，也不使用任务artifacts下载。
**费率与开放状态分开核对**：Muse Spark已确认改为 **¥0.01/次成功回复**；MiniMax M3继续按下表的token费率计费。`price_status: formal` 表示售价已确认，不自动授予提交权限。Muse Spark的开放状态以上方实时目录为准。只有 `open: true`、完整规格符合且本人账号/Key获权时才可提交；文档页会按实时目录显示状态。不能把供应商usage缺失或为0解释成免费，也不能用本地token估算替代M3实际计量。
| 模型 | 已确认输入价 | 已确认输出价 | 已确认缓存读取价 | 当前计量限制 |
| --- | ---: | ---: | ---: | --- |
| `MiniMax-M3` | ¥4.20/百万token | ¥16.80/百万token | ¥0.84/百万token | 原生用量包含输入、输出、缓存命中；开放以实时目录为准 |
确认的费率不是立即可提交的承诺。M3需有效的 `token_prices_cny`，其 `price_per_unit_cny: null` 不表示免费，也不能回退成每次固定价。Muse Spark使用 `unit: request`、`price_per_unit_cny: 0.01`，不再以token计价；目录关闭或价格待确认时均不可提交。
### 普通回复与SSE
以下示例只在对应模型正式开放且Key获权后可调用。发送一次；超时、断流或5xx保留提交时间和原响应，先查用量，不自动重试POST。
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/v1/chat/completions' \
-H "Authorization: Bearer $COINSEED_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary '{"model":"MiniMax-M3","messages":[{"role":"user","content":"用一句话解释关键帧。"}],"stream":false,"n":1,"max_completion_tokens":32768,"tools":[],"tool_choice":"none"}' \
--output reply.json
```
普通JSON读取 `choices[0].message.content`、`finish_reason`，M3还需核对 `usage`。Muse Spark调用时将model改成 `muse-spark`，并删除M3的 `max_completion_tokens`，可省略输出上限，或用 `max_tokens` 指定本次上限；按次回复不要求usage为正数，但仍须非空文字以及合法终态 `stop` 或 `length`。`length` 表示达到调用者或上游的输出上限，仍是有效完成并计1次；续写属于新的计费回复。这里的传输截断指断流且无完整合法结束标记，不是 `length`。此段描述Chat Completions；Spark另支持下方原生Responses文字接口，实际工具执行未开放。
```bash
curl --fail-with-body --no-buffer --silent --show-error \
'https://api.coinseed.net/v1/chat/completions' \
-H "Authorization: Bearer $COINSEED_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary '{"model":"MiniMax-M3","messages":[{"role":"user","content":"给我三个镜头建议。"}],"stream":true,"stream_options":{"include_usage":true},"n":1,"max_completion_tokens":32768,"tools":[],"tool_choice":"none"}'
```
SSE可能跨网络分块，按空行分隔完整事件再解析；`data:`为JSON，文字在 `choices[0].delta.content`。完成需要模型的 `finish_reason` 和正常结束信号，网关可能将上游正常EOF归一为 `data: [DONE]`。不要把单独 `[DONE]`、HTTP200、连接断开或部分文字当成完整业务完成。最后的usage事件不一定含文字；支持 `include_usage` 也不等于供应商必然提供可信用量。网页“停止接收”只停本机读取，不保证上游取消或不计费。
### 输入、上下文与结果保存
输入可粘贴整份长剧本；本站的1,048,576个Unicode字符保护上限与供应商的token上下文窗口是两种单位，不能互相等同。输入还受实际上游token窗口约束；超过窗口时由上游明确拒绝，不自动截断文本或重发。Muse Spark文字JSON保留16MiB请求保护上限；M3原始与转换后的JSON采用模型服务的64MB请求上限，字符上限按解码后的文本合计计算，UTF-8与合法Unicode转义均可。Muse Spark不设本站输出token上限；未传 `max_tokens` 时不强塞该参数，显式指定时原样保留；MiniMax-M3默认及本站保护上限为32,768输出token，可指定1–32,768的较小整数上限。n=1与已确认费率不变。MiniMax长输入先按最终JSON字节数+4096及实际最终输出上限保守预占，成功后按原始实际usage结算并退差，失败走原完整退款；临时预占可能高于最终实扣。
网页文字对话及本地文件提取，每次最多128条已完整完成的对话消息，内容合计最多1,048,576个Unicode字符（字符保护上限，不是token数）；中断轮次显示供核对，但不自动带入下轮。刷新、关闭或换账号清除本页对话，可先“下载对话”保存TXT。后台有用量日志，不等于可恢复全部聊天正文。
- M3 API与网页同为合计最多1,048,576个Unicode字符、1–128条 `system/user/assistant` 消息；仅user可附已验PNG/JPEG/WEBP本地图片（最多4张，每张10MB（官方上限），dataURL且detail=low），system/assistant仍纯文本。不接受视频、原生PDF/DOCX、工具调用、其他模型别名、透传或Responses转发。服务端固定 `n=1`、关闭thinking并采用standard tier；输出未指定时默认32,768，`max_tokens`（兼容旧客户端）或 `max_completion_tokens` 接受1–32,768整数，指定较小值会保留并参与预占；两字段同时存在时必须相等。通道最终只发送 `max_completion_tokens`。32,768是本站保护上限，不代表供应商的模型最大输出能力。最终不支持的参数明确拒绝。
- Muse Spark按次合同限定API与网页的整份输入合计最多1,048,576个Unicode字符、1–128条 `system/user/assistant/developer/tool` 文字消息，content可为字符串或文字内容数组，并可携带文本形式的工具调用历史、`n=1`、不设本站输出token上限、空工具且 `tool_choice: none`。这些字段不构成供应商内部agent实际耗时或行为的硬保证。开放状态以上方实时目录为准；已开放且获本人账号/Key权限才可提交。
- M3的图片输入只用于理解，不等于生图/配音输出；Spark未开放图片输入。两模型均可导入TXT、MD、JSON、CSV、TSV、SRT、VTT、文字PDF和DOCX正文：在浏览器本地提取文字后，只有点击发送才提交文字。加密/扫描PDF明确拒绝；原文件、DOCX内图片及外部链接不会上传。文件全文和已完成上下文共同计入字符保护额度，超出时拒绝、不自动截断。
### Muse Spark按次回复（开放状态见实时目录）
每次成功回复收¥0.01；携带历史上下文继续提问是新请求，再计1次。一次流式回复的多个SSE分片不会分别收费。按次费用与供应商返回的token数量无关，usage缺失或为0既不表示免费，也不授予模型权限。
普通JSON需要完整有效响应；SSE需要合法事件和完整结束标记。两者都要求非空文字与 `stop` 或 `length` 终态；`length` 是达到调用者或上游的输出上限，仍计1次，继续提问或续写另计新回复。网关因网络中断未收到完整合法终态或结束标记时按失败处理，不收本次回复费；已预占的额度退回。浏览器本地停止接收或断网不等于网关也未完成，不能仅凭部分文字自行判定退款；保留原请求和时间，核对后台用量及余额，不自动重发。此价格已确认；开放状态以上方实时目录为准，已开放且获本人账号/Key权限才可提交。
### Muse Spark原生Responses（老曾来源）
`POST /v1/responses` 已通过普通账号公网JSON和SSE实测。使用本人Key，并指定 `X-Coinseed-Provider: muse-laozeng`。模型仍是 `muse-spark`，每次完整文字回复¥0.01，原生响应ID与事件原样保留，不转换成Chat Completions格式。
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/v1/responses' \
-H "Authorization: Bearer $COINSEED_API_KEY" \
-H 'X-Coinseed-Provider: muse-laozeng' \
-H 'Content-Type: application/json' \
--data-binary '{"model":"muse-spark","instructions":"用中文简短回答。","input":[{"role":"user","content":[{"type":"input_text","text":"解释关键帧。"}]}],"stream":false,"store":false}'
```
普通JSON读取 `output` 中的 `output_text`；成功须 `status: completed` 且有非空文字。将 `stream` 改为true可接收原生SSE，拼接 `response.output_text.delta`，以 `response.completed` 中的完整响应核对交付；不要求Chat接口的 `[DONE]`。HTTP200、部分文字或仅连接结束不表示完整回复。
`input`可为字符串、文字消息或文字内容数组；支持 `instructions`、developer消息，以及客户端传入的 `function_call` / `function_call_output` 文本历史。每次发送所需的完整文字上下文，不使用 `previous_response_id` 续接，不提供服务端历史恢复。可选 `max_output_tokens` 设置本次上限，未指定时由上游决定。图片、音频及实际函数执行没有开放；工具历史仅作为文字上下文。
与Chat相同，每次完整回复计1次，usage为0不表示免费；查询用量和保存已有回执不创建新回复。网关未获得完整合法结果时，核对原请求与用量，不自动重发。
### M3预占、实际计费和退款
每次发送（包括携带历史上下文的后续轮次）都是新请求，整份本次输入参与计量。非缓存输入、缓存读取和输出分别计价；若上游输入总数已包含缓存命中，缓存部分只按缓存价计一次，不同时按普通输入价重复收费。输出以供应商usage口径为准。
例如一次可信usage为输入1000 token（其中缓存200）、输出100：
`(1000−200)×4.20/1,000,000 + 200×0.84/1,000,000 + 100×16.80/1,000,000 = ¥0.005208`
这是费率算例，实际账单受网关内部配额舍入影响；不按中文字符数、网页字数或每请求固定价代替token。
已部署的M3保护在供应商调用前，依据最终发送请求的保守输入预算和实际最终输出上限（未指定时32,768）检查并原子预占钱包及有限Key额度。预留额会大于短回复实际费用；余额只够“估计一小段答案”但不足预留时会拒绝。关闭本地token统计、信任额度或并发请求不会绕过此检查。
成功按实际usage扣费并退回预留差额；明确失败按网关记录退回对应预占。若供应商异常上报超过受保护预留，客户本单最多扣已预占额度，平台承担差额，管理审计保留原usage、应收、实收及差额；不会在已输出流式内容后伪称整单退款。浏览器断流仍需查用量，不能凭停止按钮判定退款。Muse Spark另按次结算，不套用本段M3的token预占算例；开放状态以实时目录及本人账号/Key权限为准。
## MiniMax 原生图片与配音（价格已确认，开放以实时目录为准）
`image-01` / `image-01-live` 是同步文字生图；`speech-2.8-turbo` / `speech-2.8-hd` 是同步系统音色配音。对应网关保护及正式费率已配置；**四模型分别核对实时目录**。处于 `awaiting_ordinary_account_acceptance` 时尚待普通账号验收，不可提交；验收完成并设为 `open: true` 后，仍须本人账号与Key获权且输入符合完整规格。这里只说明目前受保护的首批规格，不代表供应商的全部能力已接入。
| 模型 | 首批受保护规格 | 已确认正式费率 |
| --- | --- | --- |
| `image-01` | 八种已开放比例或成对自定义尺寸、1张、关闭prompt_optimizer | ¥0.05/实际交付张 |
| `image-01-live` | 七种已开放比例、1张；独立型号，不支持custom/21:9 | ¥0.05/实际交付张 |
| `speech-2.8-turbo` | `male-qn-qingse`、speed=1、普通文字、MP3 | ¥4/万计费字符 |
| `speech-2.8-hd` | 同上；独立高清语音型号 | ¥7/万计费字符 |
网页和API都须满足目录 `native_media_specs` 或 image-01 专属 `native_image_custom_size` 完整规则。未开放参考图、目录外比例/尺寸、批量、其他音色/音频格式的请求在上游调用前拒绝；不能静默丢掉参数再收费。标准 `user` 可选短字符串、最多256字符，仅作客户标记；不扩展生成能力。原始JSON最大32KiB。
### 同步文字生图与下载
`POST /v1/images/generations`；文字提示词1–1500 Unicode字符，PNG/JPEG/WebP交付。只接受 `response_format: b64_json`，不返回外站URL。
```json
{"model":"image-01","prompt":"白色背景上的蓝色陶瓷杯，柔和侧光","n":1,"aspect_ratio":"1:1","response_format":"b64_json","prompt_optimizer":false}
```
`image-01` 的比例为1:1 / 16:9 / 9:16 / 4:3 / 3:4 / 3:2 / 2:3 / 21:9；`image-01-live` 使用前七种，不支持21:9或自定义尺寸。仅 `image-01` 可改用成对 `width`、`height`：每边512–2048整数像素且均为8的倍数，此时不得同时传 `aspect_ratio`。例如 `{"model":"image-01","prompt":"蓝色陶瓷杯","n":1,"width":800,"height":1200,"response_format":"b64_json","prompt_optimizer":false}`。
省略尺寸和比例时默认1:1；`n=1`、`prompt_optimizer=false`，冲突值拒绝。**不接受 `size`、subject_reference（含null）、image/images、mask、多图编辑、远程URL或其它生成字段。** 人物参考能力仍是后续独立接入项。开放比例依据已核能力合同与交付几何验证，不表示每个型号/比例均有独立付费样本。
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/v1/images/generations' \
-H "Authorization: Bearer $COINSEED_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @image-request.json --output image-response.json
```
保存JSON后检查无业务error、`data`恰有一个非空 `b64_json`，Base64解码得到原图片文件，再根据真实MIME保存扩展名。服务端验证实际图片完整可解码、标准Base64、最多8MiB、边长≤4096且总像素≤16,777,216；比例模式核对所选比例（相对误差≤3.5%，1:1须宽高相等），自定义尺寸模式须精确匹配请求宽高；不承诺比例模式的固定像素尺寸。空输出、数量不符、URL替代、损坏或越界作品不会作为成功交付收费。
```python
import base64, json
from pathlib import Path
from PIL import Image # pip install pillow
import io
result = json.loads(Path("image-response.json").read_text())
items = result.get("data", [])
if result.get("error") or len(items) != 1 or items[0].get("url"):
raise RuntimeError("交付未确认，保留响应并核对用量，不重复生成")
raw = base64.b64decode(items[0]["b64_json"], validate=True)
if not 0 < len(raw) <= 8 * 1024 * 1024:
raise RuntimeError("图片大小不符")
request = json.loads(Path("image-request.json").read_text())
with Image.open(io.BytesIO(raw)) as image:
image.load()
if not (0 < image.width <= 4096 and 0 < image.height <= 4096) or image.width * image.height > 16777216:
raise RuntimeError("图片尺寸超界")
if "width" in request or "height" in request:
if (image.width, image.height) != (request.get("width"), request.get("height")):
raise RuntimeError("自定义尺寸未按原值交付")
else:
a, b = map(int, request.get("aspect_ratio", "1:1").split(":"))
if (a == b and image.width != image.height) or abs(image.width / image.height / (a / b) - 1) > .035:
raise RuntimeError("交付比例不符")
extension = {"PNG":"png", "JPEG":"jpg", "WEBP":"webp"}[image.format]
Path("result." + extension).write_bytes(raw)
```
### 同步配音与MP3下载
`POST /v1/audio/speech`；输入1–2000 Unicode字符的普通文字，不含语气/停顿/发音标记。首批仅中文系统声线 `male-qn-qingse`、speed=1；未开放克隆、混音、声线设计、其他系统音色、发音词典或流式音频。音色选择不代表所有供应商音色均已验证。
```json
{"model":"speech-2.8-turbo","input":"你好，欢迎来到创作台。","voice":"male-qn-qingse","speed":1,"response_format":"mp3","metadata":{"output_format":"hex","audio_setting":{"format":"mp3","sample_rate":32000,"bitrate":128000,"channel":1}}}
```
固定MP3、32kHz、128kbps、单声道。voice必填；speed/response_format及固定metadata可省略，网关填同值，冲突值拒绝。metadata仅允许上述白名单，不允许覆盖model、text、voice_setting、stream等字段。供应商hex由服务器转换成同源MP3二进制，客户端不必跟随外站地址或自行解hex。
```bash
curl --fail-with-body --silent --show-error \
'https://api.coinseed.net/v1/audio/speech' \
-H "Authorization: Bearer $COINSEED_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @speech-request.json --dump-header speech.headers --output speech.mp3
```
先确认HTTP成功及 `Content-Type: audio/mpeg`，再播放/完整解码；错误正文不能当MP3。网关须取得供应商完成态、正的真实usage和有效MP3后才输出成功；最多16MiB，非音频hex、部分结果或缺失用量不会作为成功零费用交付。
### 字符计费、预占与临时文件
**输入字符不等于计费字符。** Speech 2.8提交前按每个Unicode字符最多2个计费字符的保守上限预占，钱包与有限Key都须足额；成功按供应商 `usage_characters` 结算并退差。输入、metadata不能扩写到未计量的另一份文本。实际usage缺失或异常超出已保护上限时按失败/核对路径处理，不成功放行后补成负余额。
已有样本“你好，欢迎来到创作台。”是11个Unicode字符，供应商记录20个计费字符。按已确认费率，Turbo为 `20×4/10000=¥0.008`，HD为 `20×7/10000=¥0.014`；预留上限22个字符，最终只按20个结算。内部配额舍入以账单为准，不能直接用JS.length或屏幕字数当最终费用。
**原生同步结果不是任务库。** 没有本站异步task_id，也不自动进入“我的作品”。网页仅保存当前账号当前页最多5份临时图片/音频，可播放、预览、下载；刷新、关闭或换账号即丢失。要用于后续参考生成，先下载，再按那个模型已开放的素材流程上传，不能引用一个不存在的原生task_id。
取消接收、网络中断和超时不会自动重发，也不等于供应商已取消或网关已退款。先核对用量、请求时间与响应；确认后手动重新发送的是另一个请求。API调用方应自行保存成功返回的字节。
图片比例与自定义尺寸按模型目录已验收范围提供：MiniMax image-01 可选择1:1、16:9、9:16、4:3、3:4、3:2、2:3、21:9；自定义使用同时存在的顶层 `width` 和 `height`，各为512–2048的整数、8的倍数，并完全省略 `aspect_ratio`。image-01-live 仅前七种比例，不支持21:9和自定义宽高。网页每次仍1张、`response_format:b64_json`、`prompt_optimizer:false`，原价格不变；图片实际像素以解码交付文件为准，不将比例标签当作分辨率保证。
## H3质量：文字、首帧及首尾帧
仅6秒竖屏768×1344、158帧/24fps，不叠加超分。标准FL2VA、20步、无LoRA；按6秒收费。POST /coinseed/v1/jobs，查询GET /coinseed/v1/jobs/{task_id}。
| video_workflow | asset_tasks | 费用 |
| --- | --- | --- |
| fl2va_text | [] | 0.90元 |
| fl2va_first | [首帧任务号] | 0.90元 |
| fl2va_first_last | [首帧任务号, 尾帧任务号] | 1.00元 |
```json
{
"model": "h3-quality",
"video_workflow": "fl2va_first_last",
"prompt": "人物向前走两步，镜头缓慢推进",
"seconds": 6,
"orientation": "portrait",
"asset_tasks": [
"task_MY_FIRST_FRAME",
"task_MY_LAST_FRAME"
]
}
```
图片为本人coinseed-asset上传完成的PNG/JPEG/WebP，规范化元数据尺寸须768×1344。两张图不得重复，顺序为首帧后尾帧。首帧拉伸、尾帧中心裁剪。当前不提供其他尺寸、音视频参考、max或超分组合。下载通过GET /v1/tasks/{task_id}/artifacts；查询/重复下载不收费，失败沿用退款流程，未知结果不重复提交。正式开放以实时目录为准。
## H3 新增已验规格
仅以实时目录列出的完整组合为准，不能交叉组合。新增固定档位使用 POST /coinseed-h3-presets/v1/jobs，查询使用 GET /coinseed-h3-presets/v1/jobs/{task_id}；普通H3、音频、多图和max仍使用原 POST /coinseed/v1/jobs。普通H3的图片、视频、音频先上传为自己的coinseed-asset任务；四个固定档的参考图改用coinseed-h3-preset-asset，不能混用。普通组与模型权限仍由网关核对。
Turbo 8步6秒竖屏0.48元、Sage 20步6秒竖屏0.90元、轻量固定4步4秒横屏0.20元、细节固定30步6秒竖屏1.35元。上述基础档均单图、无视频/音频参考；参数不可覆写。需要2K/4K时只能选择超分章节列出的同工作流组合：2K ¥0.04/实际秒、最低¥0.20；4K ¥0.08/实际秒、最低¥0.40，基础生成费另计。6秒档原生768×1344、158帧24fps，实际约6.58秒；轻量4秒档960×544、107帧24fps，实际约4.46秒，不裁切或补帧。
H3测试6秒横屏：单图加1/2/3段独立2秒音频；同档可使用2秒竖屏视频的原声加三段2秒音频。H3质量6秒竖屏：单图加三段30秒音频。独立音频字段为 reference_audio_tasks 对象，槽位audio1/audio2/audio3，只能引用本人已完成的音频上传任务；use_reference_video_audio=true启用原片声音。原片声音占