糯米 API开发文档
NUOMI / API REFERENCE

把糯米 API
接入你的应用

从获取客户密钥，到提交图片和视频任务，再到读取结果。按顺序完成一次完整接入。

BASE URL · 当前站点当前页面所在站点

Base URL 填到域名或端口即可，不加 /v1。外部应用使用本站创建的客户密钥。

01 / OVERVIEW

接口总览

图片和视频采用异步任务：先确认报价，再提交一次，保存任务编号并持续查询。本文档示例只提供复制与下载，不会在页面中执行生成。

GET/v1/models

已开通模型、价格与能力约束

 POST/v1/images

创建图片任务

 POST/v1/videos

创建图片或视频任务

 GET/v1/videos/{task_id}

查询进度、结果与结算状态

 GET/v1/tasks/by-client-request-id

按业务编号找回原任务

 GET/v1/usage/logs

实际消费与额度退回明细

当前调用接口覆盖图片与视频任务。模型广场中的聊天、音频或其他能力标签，不代表本站已开放对应的聊天、SSE 流式接口。

02 / AUTHENTICATION

准备客户密钥

  1. 注册并验证邮箱进入本站工作台，使用自己的邮箱和密码登录。
  2. 为钱包准备余额在钱包兑换本站运营方提供的充值码。充值码和账户只适用于创建它们的站点。
  3. 创建 API 密钥在API 密钥页面创建密钥并保存完整内容。外部应用与工作台共用该账户余额。

API 使用 Bearer 认证。将密钥保存在自己应用的服务端环境变量中；不要写入网页代码、公开仓库或移动端安装包。

服务端环境变量
加载示例…
HTTP 请求头
加载示例…

下文使用 NUOMI_BASE_URL 和 NUOMI_API_KEY。同一账户的有效客户密钥可以查询该账户的任务；它们不能访问其他账户的任务、素材或账单。

03 / DISCOVERY

先获取模型与当前报价

GET/v1/modelsBearer 认证

提交前读取模型列表，使用返回的完整 id，同时保存 price_revision。向用户展示单价和预计用量，确认后再创建任务。

cURL · 获取可调用模型
加载示例…
返回字段示意 · 非实时价格
加载示例…
字段用于决定什么
id / kind准确模型名称，以及 image 或 video 类型。
price_cny / billing_unit人民币单价文本；task 按次，second 按生成秒数。图片始终按次。
price_revision本次报价版本，提交时原样填写；不要自行计算或缓存为永久值。
allowed_aspect_ratios / allowed_quality / allowed_sizes可用比例、质量和尺寸。空的尺寸列表表示应省略 size。
min_seconds / max_seconds / fixed_seconds / duration_options时长范围、固定时长和可选时长集合。
reference_limits图片、视频、音频参考素材的最少和最多数量。

模型广场与可调用模型有区别。GET /api/catalog 是公开展示目录；GET /v1/models 和 GET /api/pricing 返回本站当前已开通的调用模型。调用前应以后两者为准。

04 / IMAGE GENERATION

创建图片任务

POST/v1/images

选择 kind: "image" 的模型，将它的名称和报价版本填入请求。以下占位值必须替换；参考素材和质量字段可按需增加。

image-request.json
加载示例…
cURL · 提交已确认的图片请求
加载示例…

新任务返回 HTTP 202，保存 id。同一业务编号、相同有效参数的重试返回原任务和 HTTP 200。图片也可使用 POST /v1/videos 创建，类型由模型决定。

图片的 seconds 省略或设为字符串 "1"，不能填写 mySeconds。默认质量取模型 allowed_quality 的第一项。

05 / VIDEO GENERATION

创建视频任务

POST/v1/videos

选择 kind: "video" 的模型，按模型声明选择真实时长。视频当前支持 16:9 和 9:16。

video-request.json · 时长以模型范围为准
加载示例…
cURL · 提交已确认的视频请求
加载示例…

示例的 4 秒只适用于允许该时长的模型。若返回 fixed_seconds，必须使用固定秒数；若 duration_options 非空，必须从中选择。服务端会处理模型所需的时长字段归一化。

06 / REQUEST PARAMETERS

参数与模型规则

参数类型 / 必填说明
modelstring / 是从 /v1/models 复制的完整模型 ID。
promptstring / 是非空提示词，最多 32,000 个字符。
client_request_idstring / 二选一稳定业务编号，最多 191 字符；也可由 Idempotency-Key 请求头提供。
price_revisionstring / 核价必需对应模型返回的 64 位报价版本。原样传入。
aspect_ratiostring / 可选从 allowed_aspect_ratios 选择；图片默认 1:1，视频默认 16:9。
secondsstring / 视频必填实际生成秒数的整数字符串，例如 "4"。图片为 "1"。
mySecondsstring / 按模型带独立 -Ns 时长标记的模型可用；通常直接提供实际 seconds 即可。
qualitystring / 可选仅接受模型 allowed_quality 中的值。
sizestring / 可选必须是 allowed_sizes 中的值，例如 1280x720。未配置时省略。
reference_image_urlsstring[] / 可选图片参考地址，数量必须符合模型约束。
reference_videosstring[] / 可选视频参考地址；不接受参考视频的模型会拒绝该输入。
reference_audiosstring[] / 可选音频参考地址，数量必须符合模型约束。

时长与参考能力

  • 没有独立 -Ns 标记的模型，使用 seconds，省略 mySeconds。
  • 带独立 -Ns 的模型，本站可接收实际 seconds 并归一化；显式传参也可使用 seconds: "1" 与 mySeconds: "实际秒数"。
  • 带固定时长规则的模型使用 fixed_seconds；所需最少参考图数量从 reference_limits.min_images 读取。
  • -nv 模型不接受参考视频，传入会返回参数错误。

参考字段兼容 image_urls / images、video_urls / videos、audio_urls / audios，但同一类的规范字段和别名只能填写一种。建议始终使用表格中的规范字段。

只发送本站支持的字段。不要从其他平台的请求体直接附带 resolution、persist、stream 或 bypass_face_check；未知字段会返回参数错误。

07 / REFERENCE MEDIA

使用参考素材

真实生成使用可公开直接读取的 HTTP(S) 文件地址。不要传电脑路径、blob:、内网地址、需要登录的网页或仅当前浏览器能打开的地址。按模型的参考类型和数量限制提交。

参考字段片段 · 示例地址需替换
加载示例…

本机私有素材上传

PUT/workbench/api/uploadsBearer 认证

上传接口用于按账户保存素材。查询参数为 model、kind（image / video / audio）和 filename，请求体是文件的原始字节，不是 JSON 或 multipart 表单。模型必须支持该参考类型。

cURL · 上传图片到本站素材库
加载示例…

当前默认上限为图片 20 MiB、视频 100 MiB、音频 50 MiB。支持 PNG、JPEG、WebP、GIF，MP4 / MOV，MP3 / WAV / M4A；类型、文件内容与扩展名必须匹配。

成功返回 id、type、name、mime、size、私有预览地址 preview_url 和本站引用标识 reference_url。素材与预览只能由所属账户访问。

私有上传成功不等于已获得公网生成地址。当前本机上传的 reference_url 用于私有素材管理与模拟流程；尚未配置公网素材存储时，真实生成会返回 upload_public_storage_required。此时请使用自己的公网文件直链，或联系运营确认素材存储已开通。不要把 preview_url 当作公网地址。

提示词中的 @图片1、@视频1、@音频1 对应各类数组中的顺序。引用前应先提供该编号的素材；不要引用不存在的编号。

08 / IDEMPOTENCY

先保存业务编号，再提交

为一笔生成业务分配稳定、唯一的 client_request_id，在请求前保存编号与完整参数。也可使用 Idempotency-Key 请求头；两者同时提供时必须一致。编号最多 191 字符，不能含控制字符。

情况本站行为与处理方法
新编号、有效请求创建新任务，返回 HTTP 202。保存返回的 id。
同一账户、同编号、相同有效参数HTTP 200 返回原任务，不再次创建或重复预留费用。
同编号、不同有效参数HTTP 409，error.code: invalid_request，message: idempotency_conflict。应找回原任务，不要覆盖原参数。
连接中断、提交超时或 5xx先用原编号查找；查询暂时失败不代表任务没创建。必要时保持原编号与原参数重试。
原任务已失败，决定重新生成先查清失败原因并重新确认报价；创建新业务编号。旧编号仍指向旧任务。
GET/v1/tasks/by-client-request-id
cURL · 找回已创建的任务
加载示例…

查询参数按 URL 规则编码。任务归属于客户账户，同账户下的有效密钥可以查询；不存在或不属于该账户时返回 404。查到后取 id || task_id 继续查询任务状态。

请始终保留自己的业务编号和返回任务编号。不要把一次网络错误变成一个新编号，这可能创建另一笔任务。

09 / PRICE CONFIRMATION

价格变动时，先重新确认

本站在创建前核对当前报价，并在转发前复核。新请求中的 price_revision 应来自用户最后确认的模型报价；缺少报价版本也可能触发报价确认错误。

HTTP 409 · 报价已变化
加载示例…
尚未创建任务

HTTP 409 · 报价变动

确认 error.code 是 model_price_changed，将新报价展示给用户并等待确认。确认后用返回的 model / price_revision 更新请求；本次未创建任务，可保留原业务编号重发。

任务已创建

查询返回 failed

若任务的 error.code 为价格或模型变动，原任务已经结束。刷新模型和报价，用户确认后使用新的业务编号重新生成。

不要在收到价格变动后自动按新价格继续调用。410 model_unavailable 表示模型已不可用；503 price_check_unavailable 表示暂时无法核价，保留业务信息并稍后查询或重试。

10 / TASK RESULTS

持续查询，直到得到明确结果

GET/v1/videos/{task_id}

图片也可使用 GET /v1/images/{task_id}。建议每 3–5 秒查询一次；遵守接口速率限制。部分接入模式由首次任务查询启动处理，创建后应按任务编号继续查询。

cURL · 查询任务
加载示例…
queuedprocessingcompleted或failed
任务字段示意 · 完成状态
加载示例…
  • queued / processing：继续等待。未记录实际百分比时 progress 为 null；完成时为 100。
  • completed：读取结果地址。视频优先用 video_url，再兼容 url / result_url；图片使用 url / result_url。
  • failed：读取任务内的 error。预留额度按任务结算结果退回，先处理原因再决定是否新建任务。
  • 查询报错、暂时查不到、响应为空，或成功状态却没有结果地址：保留任务编号，继续等待或联系运营核查，不要自行认定生成失败并重复下单。

billing.state 的 reserved 表示预留额度，charged 表示已扣费，released 表示预留已退回。人民币金额以文本返回，最多保留 6 位小数。

11 / CLIENT EXAMPLES

服务端调用助手

下载示例后放进自己的服务端项目。助手不在导入时创建任务；调用生成函数前，仍需完成参数检查、保存业务编号和用户报价确认。

JS
JavaScript / Node.jsNode.js 18+ · 原生 fetch
PY
Python标准库 · 无额外依赖

将已经向用户展示并确认的请求保存为 confirmed-request.json，包含当时的 price_revision 与稳定业务编号，再运行以下服务端代码。收到价格变动错误时应暂停，交回用户确认。

JavaScript · 读取已确认的请求并保存任务编号
加载示例…
Python · 读取已确认的请求并保存任务编号
加载示例…

完整助手将 HTTP 错误与任务失败分开处理，保留任务编号，提供有限次数的轮询。轮询达到上限只表示停止本次等待，不会取消原任务或自动重新生成。

查看 JavaScript 完整示例
nuomi-media.mjs
展开后加载本地示例文件…
查看 Python 完整示例
nuomi_media.py
展开后加载本地示例文件…
12 / BALANCE & USAGE

核对余额和实际消费

GET/v1/balance

返回 currency、可用余额 available 和预留额度 reserved。工作台与客户 API 共用钱包。

GET/v1/usage/logs

按账户读取已结算消费或额度退回。参数包括 page、limit（1–100）、模型名称 model、entry_type（all / consume / release）、UNIX 秒数 start_time / end_time，以及 group=default。时间范围按结算时间筛选。

cURL · 查询余额与消费
加载示例…

结果含 data、total、分页字段和 summary。summary.total_spent 是整个筛选结果的实际消费合计；额度退回条目的 cost 为 0，退回金额单独放在 billing.released_amount。未采集的 Token 或速率数据返回 null。

也可直接打开 使用日志、任务记录 或钱包核对。

13 / TROUBLESHOOTING

错误码与排查

HTTP 错误通常是 { "error": { "code": "…", "message": "…" } }。查询参数的框架校验可能返回 HTTP 422 与 detail 数组。HTTP 200 的任务对象仍可能是 status: "failed"，需要单独检查。

HTTP常见代码处理方法
400invalid_request / invalid_json / unknown_model / invalid_price_revision / invalid_endpoint按错误信息修正参数，重新查询已开通模型；不要自动换编号反复提交。
401invalid_api_key检查本站客户密钥是否正确、有效，并使用 Bearer 请求头。
402insufficient_balance核对可用余额，在同一站点充值后再提交。
404task_not_found确认任务编号、站点和账户。提交曾超时时，按原业务编号找回。
409model_price_changed 或 invalid_request分别按“价格变动”或“业务编号冲突”流程处理。
410model_unavailable模型已不可用，刷新模型列表并重新选择。
413body_too_large / upload_too_large缩小请求或素材文件，遵守对应上限。
422查询参数校验检查参数类型、范围与时间格式。
429rate_limit_exceeded / too_many_pending_tasks降低频率或等待已有任务结束，按原编号恢复，不盲目创建新任务。
503not_configured / price_check_unavailable / upload_public_storage_required对应配置、核价或素材存储暂不可用。保留任务信息，稍后重查或联系运营。

接入前再核对一次

当前站点、客户密钥、模型与报价版本、业务编号、参考素材、提交和轮询。先在自己的测试环境验证恢复流程，再向客户开放。

查看模型广场