This page is available in Chinese only for now. Code samples, request fields and URLs are the same in every language.

快速开始

从实时能力目录选择图片、语音等模型，调用 API 并安全获取结果。

平台使用统一的 Bearer API 密钥。每个 /v1/models 条目的 id 就是请求里的 model；不同条目的输入字段可能不同，不能只换 model 而沿用旧参数。

1. 获取密钥和调用地址

登录API 密钥创建密钥，并在余额充值确认余额足够。密钥只保存在服务端环境变量，不要放进前端代码或公开仓库。

从能力详情的 API 页、该能力的 llms.txt 或 Schema 的 servers 获取 API 地址。官网目录和生成 API 可能位于不同域名，不要混用。

export MUSESPAN_API_BASE="https://api.musespan.com"
export MODEL_ID="从模型详情页复制的公共模型ID"
export MUSESPAN_API_KEY="从控制台创建的平台密钥"

本文命令使用 MUSESPAN_API_KEY 保存密钥，MUSESPAN_API_BASE 保存生成 API 的源站地址（不含 /v1）。读取原始 Markdown 的 Agent 应从网站 /llms.txt 获取实际 API base URL。

2. 选择能力并读取当前契约

先读取本站的精简目录，需要所有输入约束时再读取展开目录。带不带 Bearer API 密钥，返回的目录都相同；带密钥时只校验密钥是否有效。可用 ?category=image-to-image 等按能力类型筛选（不需要分页）。

复制目录条目的 id 作为请求的 model，不要自己拼。图片和视频的 id 以能力结尾（例如 alibaba/wan-2.7/image-to-image），一个模型可以有多个能力；音频模型只有一个能力，它的 id 通常就是模型 ID（厂商/模型 两段，与 group.id 相同）。group.id 与 id 不同时只用于分组，不能填进 model。不要填写模型厂商自己的接入点。

在能力详情点击 OpenAPI 查看接口定义；Agent 也可以读取该条目的 openapi_url 或 llms 链接（图片和视频为 /models/厂商/模型/能力/llms.txt，音频为 /models/厂商/模型/llms.txt），获取实时参数、价格和 cURL、JavaScript、Python 示例。仅使用契约声明的参数及合法值，输入图片的格式、数量和尺寸约束也以该能力为准。

将单能力文档里的 Full Example JSON 保存为 input.json，按需修改提示词和合法参数。保留示例里的 model。图片编辑还需要提供有效参考图片，不能直接使用示例占位地址。

文字转语音（?category=text-to-speech）等模型任务能力使用 POST /v1/model-tasks，model 填条目的 id（音频通常就是 厂商/模型 两段的模型 ID），厂商参数放在 input 内，提交时必须带 X-Request-Id；完成后用提交任务的同一把密钥下载声明的结果文件。模型任务超过可同时运行的数量时会先排队（queued，带估计的 queue_position），提交 5 分钟后仍在排队会以 queue_timeout 失败并全额退款；排队中的任务可用 POST /v1/model-tasks/{id}/cancel 取消并全额退款。模型任务的轮询等待上限建议 25 分钟。音频文件以 application/octet-stream 返回，请按文件头识别格式（ID3 或 MPEG 帧头为 MP3，RIFF…WAVE 为 WAV，OggS 为 Ogg/Opus，fLaC 为 FLAC）后保存。完整步骤和示例见该能力的 llms.txt。

3. 图片生成与编辑：按能力选择同步或异步接口

先查看能力详情的 OpenAPI 或展开目录中的 generation.mode 和 api.endpoint。sync 能力使用 /v1/images/generations；async 能力使用 /v1/images/tasks。输入字段以选中能力的 Schema 为准，不要把一项能力的参数直接套用到另一项。

同步能力调用：

curl --fail-with-body --connect-timeout 10 --max-time 300 \
  "$MUSESPAN_API_BASE/v1/images/generations" \
  -H "Authorization: Bearer $MUSESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @input.json

成功响应含 created 和 data 数组，图片地址在 data[].url。请求多张图片时遍历数组，不要只处理第一张。

异步能力先生成一个 X-Request-Id（推荐 UUID）并保存，任务 ID 就是这个请求 ID。提交是幂等的：同一个请求 ID、同样的请求内容重复提交只会返回原任务，不会重复生成或扣费。所以提交超时、连接失败或返回 429/5xx 时，用同一个请求 ID 原样重新提交即可；不要换新 ID，也不要只靠轮询等待一个可能没送达的提交。

IMAGE_REQUEST_ID="$(openssl rand -hex 16)"
curl --fail-with-body --connect-timeout 10 --max-time 300 \
  "$MUSESPAN_API_BASE/v1/images/tasks" \
  -H "Authorization: Bearer $MUSESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: $IMAGE_REQUEST_ID" \
  --data-binary @input.json

提交成功返回 HTTP 202，返回的任务 id 与 IMAGE_REQUEST_ID 相同。使用同一把 API 密钥每 5 秒查询一次，并给等待设置总时限（建议 20 分钟）。任务受理后 15 分钟内仍未出结果、或提交后 15 分钟仍未确认时，平台会判定失败（error.code 为 generation_timeout）并全额退回预扣，所以 20 分钟内能看到最终状态：

curl --fail-with-body --connect-timeout 10 --max-time 30 \
  "$MUSESPAN_API_BASE/v1/images/tasks/$IMAGE_REQUEST_ID" \
  -H "Authorization: Bearer $MUSESPAN_API_KEY"

submitting、queued、in_progress、submission_unknown 表示还不能认定失败，继续查询原任务；查询返回 404 task_not_found 表示提交没有送达，用同一个请求 ID 原样重新提交，不要一直轮询；completed 表示图片在 data[].url，failed 表示任务失败，重新生成需换一个新的请求 ID。结果链接为限时地址，过期后可再次查询已完成的任务获取新链接。请及时保存图片；图片任务不使用视频的轮询或下载接口，当前也不支持取消。

图片任务的等待与保留

新任务完成前会先把图片保存到平台存储。status 保持兼容：存储期间仍为 in_progress，phase: "result_processing" 表示正在保存结果，继续查询原任务即可。查询任务和刷新结果链接本身不产生生成费用。

新的已存储结果保证从完成时间起可查询、下载 7 天，截止时间为 result_expires_at。
任务与幂等记录至少保留 30 天，retention_guaranteed_until 是最低保留期限，不表示届时删除；保留期内相同 ID、相同参数返回原任务，不再次生成。
data[].url_expires_at 表示本次签名链接的到期时间，最长 60 分钟，且不超过图片保留期限。链接过期后，在图片保留期限内重新查询原任务即可取得新链接。
图片到期后，生成状态仍为 completed，但 result_availability 为 expired，不再返回下载地址。历史任务标为 legacy，没有这次新增的存储保留承诺。
submitted_at、queued_at、running_at、result_received_at、completed_at 是平台记录或首次观测阶段的时间。轮询可能跳过阶段，缺失字段代表未知；不要把它们当成生成的精确开始时间。phase 可用于展示排队、生成和保存进度。

客户端等待预算用完时应保存任务 ID，稍后查询；不要因为超时自动换供应商重新生成。同步端点明确返回 unsupported_endpoint 且任务未提交生成时，可用同一个 X-Request-Id 切换到异步任务端点。

4. 视频任务：提交、轮询、下载

视频接口只用于目录中已上架的视频能力（?category=text-to-video 等筛选有结果时）；目录里没有视频能力时可跳过本节。使用视频能力的 input.json 提交一次：

curl --fail-with-body --connect-timeout 10 --max-time 300 \
  "$MUSESPAN_API_BASE/v1/videos" \
  -H "Authorization: Bearer $MUSESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @input.json

保存响应的任务 id 到 TASK_ID，使用提交时的同一把密钥，每 5 秒轮询一次：

curl --fail-with-body --connect-timeout 10 --max-time 30 \
  "$MUSESPAN_API_BASE/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $MUSESPAN_API_KEY"

queued、in_progress 表示尚未完成；completed 才能下载，failed、cancelled 停止轮询。建议单次等待最多 10 分钟，超时后保留任务 ID，之后继续查询同一任务，不要重新提交。单能力文档提供带有限轮询的完整代码。

任务完成后下载 MP4 字节流：

curl --fail-with-body --connect-timeout 10 --max-time 120 \
  "$MUSESPAN_API_BASE/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $MUSESPAN_API_KEY" \
  -o output.mp4

请及时转存；停止轮询不等于取消任务。视频的状态响应不提供可替代 /content 的公开下载地址。

5. 超时与计费

网络超时不代表生成失败，也不代表没有扣费。 重试规则按接口区分：

异步图片任务和模型任务：用同一个 X-Request-Id 原样重新提交是安全的，不会重复扣费。
视频和同步图片：不按请求 ID 去重，重发会新建并计费。不要为这类 POST 配置自动重试；已拿到视频任务 ID 时继续查询，没有拿到响应时先检查调用日志，确认结果再决定是否重发。

价格读取当前目录或单能力文档：图片按对应规则计量（例如按张；按用量计费的模型看 pricing.usage，例如按百万像素），视频按对应规则计量（例如按输出 token），语音按 pricing.usage 的每 1,000 字符单价计费（单位 thousand_characters），按输入文本的实际长度折算（空格、标点和标签都计入）。语音提交时临时冻结费用：目录 pricing.prepayment 带 scales_with 时，按本次文本的字符数冻结（scales_with.price × max(字符数, 1) ÷ scales_with.per，最多 amount；请求带有未声明的顶层字段，或其他超过 64 个字符且不是 enum/const 取值的顶层文本，或其他顶层列表、对象里的文字合计超过 64 个字符时，冻结 amount）；没有 scales_with 时，按该能力允许的最长文本冻结 amount。余额须不低于 $0.01 与本次冻结金额中的较大者。按实际用量结算：多余部分退回，超出部分从余额扣除，余额可能因此变为负数；余额为负时新请求暂停，充值后先抵扣欠款。不要把参考每秒价当作所有尺寸的固定价格。

确认失败的生成不计费；成功生成以实际结算和日志为准。视频费用可能晚于任务完成显示。视频的请求尺寸与计费对齐尺寸可能不同，详细口径在 Schema 的 x-billing-basis。

视频优先使用契约里的 resolution 和 aspect_ratio 选择请求尺寸。任务返回的 billable_size、billable_width、billable_height 表示计费尺寸，不应当作原始请求尺寸；具体字段及出现条件以该能力 Schema 为准。

详见错误处理与计费规则。