生成任务状态
通过公开任务 ID 轮询 Rivya API 生成任务,读取 queued(排队中)、processing(处理中)、succeeded(成功)、failed(失败)状态和结果 URL。
最近审阅于 2026年11月11日
使用 GET /api/v1/generations/{taskId} 查询异步生成任务。
提示词单位与完整图层结果
读取 GET /api/v1/models 时,请将 prompt_length_unit 与 max_prompt_length 一起使用。utf8_bytes 计算原文的 UTF-8 字节,包含空格和换行;utf16_code_units 计算 JavaScript 的 UTF-16 代码单元。上限为 null 不代表文字不限长或可以不填。Gemini TTS 使用字节单位。
已完成的图层拆分结果可在完整的 result.urls 之外提供 result.layers。请保留每层返回的 z_index、URL、尺寸、名称、说明和边界框,索引零是底图。TypeScript SDK 已提供这些字段。参考文件必须按所选模型上传,并传回原始签名元数据;单独声明尺寸或时长不能代替核验。
Endpoint
使用创建生成返回的公开任务 id,不是模型服务的任务 ID。这里只检查已有 Rivya 任务,不新建任务记录;聊天结果与串流使用独立会话,见聊天 API。Key 需 generations:read,部署需开启鉴权 API,密钥只在服务端 HTTPS 请求使用,见API 鉴权。
GET https://rivya.ai/api/v1/generations/{taskId}必需 header:
Authorization: Bearer rvya_sk_...curl 示例
curl https://rivya.ai/api/v1/generations/task_public_id \
-H "Authorization: Bearer rvya_sk_..."状态值
queued:已有任务记录,尚未记录最终结果或失败,不代表队列名次。processing:任务仍在进行,可能包含模型服务排队。succeeded:已记录成功结果;媒体 URL 与积分结算分别检查。failed:已记录失败,应读取error并核对结算。
前两项不是完成时间预测。后两项是生成终态,但成功任务仍可能需要积分核对。
成功响应
下例的模型、积分、时间与 URL 均为示例,不是实时报价、完成时限或真实可下载结果。succeeded 的 result 是对象,但 primary_url 可为 null,urls 可为空;成功不保证有文件可下载。文字任务在此端点只公开结果 URL,不返回全文,缺 URL 不表示失败。其他状态的 result 为 null。created_at 是创建时间,updated_at 是记录更新时间,均非预计完成时间。
{
"id": "task_public_id",
"status": "succeeded",
"model": "z-image",
"reserved_credits": 1,
"final_credits": 1,
"settlement_status": "SETTLED",
"created_at": "2026-05-10T00:00:00.000Z",
"updated_at": "2026-05-10T00:01:00.000Z",
"result": {
"primary_url": "https://media.example/result.png",
"urls": ["https://media.example/result.png"]
},
"error": null
}primary_url 是便读取的首个结果 URL。urls 在可用时包含公开结果 URL 列表。
失败响应
status: failed 必有含 code 与 message 的 error 对象;其他状态为 error: null。任务错误与状态查询本身的 HTTP 错误不同。下例展示已确认失败且预留已退回,并不代表每个失败都先扣后退:余额不足时没有成功扣除,仍须核对结算及账户交易。
{
"id": "task_public_id",
"status": "failed",
"model": "z-image",
"reserved_credits": 1,
"final_credits": 0,
"settlement_status": "REFUNDED",
"created_at": "2026-05-10T00:00:00.000Z",
"updated_at": "2026-05-10T00:01:00.000Z",
"result": null,
"error": {
"code": "generation_failed",
"message": "The generation failed."
}
}积分结算
API 与工作台使用同一账户余额。付费生成通常在提交模型服务前扣除预留积分,刷新任务状态也可能更新结算。
reserved_credits 是该任务的预留值;final_credits 是当前记录值,结算前可等于预留值。必须结合 settlement_status 读取:PENDING、RESERVED 表示尚未最终结算;SETTLED 表示用量已结算,有效最终用量小于预留时退还差额。
RECONCILIATION_REQUIRED 表示用量缺失、无效或超出预留等原因造成的待核对,仍记录原预留,不会自动追加扣除超额;后续状态检查可能更新结算。REFUNDED 表示预留积分已退回账户;FAILED 表示该任务未记录退还,和任务的 status: failed 分开,也不能单凭此值推断已扣费。
等待过久、状态不变或查询报错均不证明生成失败或积分已退还。退回的是账户积分,不是银行卡退款。参阅API 积分与失败任务及积分退回。
轮询建议
成功后可停止生成进度轮询;若结算仍为 RECONCILIATION_REQUIRED,稍后退避检查。下列间隔是客户端建议,不是完成时间或每次都查询模型服务的保证。客户端等待上限不取消任务,也不证明失败。
提交后先短暂等待,再逐步拉长轮询间隔。避免密集循环。
建议方式:
提交后等待 2-3 秒
普通任务每 5-10 秒轮询一次
长视频和音频任务适当放慢
状态变成
succeeded或failed后停止轮询
已保存状态与查询错误
Rivya 会尝试刷新符合条件的任务,但响应可能仍是上次保存的状态,例如尚在刷新间隔内,或模型服务未返回有效更新。HTTP 成功不保证刚刚查询了模型服务。
HTTP 报错或连接失败表示没有取得新任务状态。保留最后已知状态,按需重试同一状态端点,不要仅因查询失败把任务标为 failed 或重新生成。按API 错误与重试处理,保留任务 ID 和返回的 requestId,不要泄露 API 密钥。
归属边界
按账户检查归属,不按最初提交任务的某一把 Key 限定;同账户其他有效 Key 有 generations:read 且 API 开启时也可读取。不存在或其他账户的任务返回 HTTP 404 not_found。公开目录列出模型不授予任务访问权。
任务必须属于 API Key 背后的同一个 Rivya 账户。如果不存在或不属于当前账户,接口返回 not_found。
