创建生成任务
使用 model、prompt、params、Idempotency-Key 和公共响应字段提交 Rivya API 异步生成任务。
最近审阅于 2026/05/10
使用 POST /api/v1/generations 提交异步图片、视频或音频生成任务。
对 Chat 模型，请使用 Chat API。POST /api/v1/generations 不会创建 chat session 或 assistant message。
Endpoint
POST https://rivya.ai/api/v1/generations必需 headers：
Authorization: Bearer rvya_sk_...
Content-Type: application/json建议 header：
Idempotency-Key: your-unique-request-key请求体
{
"model": "z-image",
"prompt": "A clean editorial product image on a soft studio background",
"params": {
"aspect_ratio": "1:1"
},
"client_request_id": "order-123-preview"
}字段：
model：必填，公共模型 IDprompt：提示词文本，很多模型实际需要params：模型专属参数对象client_request_id：可选，来自你系统的追踪 ID
模型专属 params 见 模型 API Reference。
参考文件放入 Params
对支持上传参考素材的模型，先调用 Files API。然后把上传结果放入模型 params；生成请求不要新增顶层 files 字段。
新集成优先使用 params.referenceMediaItems：
{
"model": "nano-banana-2",
"prompt": "Restyle this product photo for a clean editorial catalog page",
"params": {
"referenceMediaItems": [
{
"url": "https://...",
"kind": "image",
"name": "reference.png",
"mimeType": "image/png"
}
]
}
}如果音频或视频输入需要时长校验，请把 /api/v1/files 返回的 duration_token 放在对应 referenceMediaItems 条目的 durationToken 字段里。
curl 示例
curl https://rivya.ai/api/v1/generations \
-H "Authorization: Bearer rvya_sk_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: product-preview-001" \
-d '{
"model": "z-image",
"prompt": "A clean editorial product image on a soft studio background",
"params": {
"aspect_ratio": "1:1"
}
}'JavaScript 示例
const response = await fetch("https://rivya.ai/api/v1/generations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.RIVYA_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "product-preview-001"
},
body: JSON.stringify({
model: "z-image",
prompt: "A clean editorial product image on a soft studio background",
params: { aspect_ratio: "1:1" }
})
});
const generation = await response.json();
console.log(generation.id, generation.status);Python 示例
import os
import requests
response = requests.post(
"https://rivya.ai/api/v1/generations",
headers={
"Authorization": f"Bearer {os.environ['RIVYA_API_KEY']}",
"Content-Type": "application/json",
"Idempotency-Key": "product-preview-001",
},
json={
"model": "z-image",
"prompt": "A clean editorial product image on a soft studio background",
"params": {"aspect_ratio": "1:1"},
},
timeout=30,
)
generation = response.json()
print(generation["id"], generation["status"])响应
{
"id": "task_public_id",
"status": "queued",
"model": "z-image",
"reserved_credits": 1,
"final_credits": 0,
"created_at": "2026-05-10T00:00:00.000Z",
"updated_at": "2026-05-10T00:00:00.000Z",
"result": null,
"error": null
}保存 id，然后轮询 生成任务状态。如果你配置了 API Webhooks，Rivya 也可以在任务进入终态时发送签名的 generation.succeeded 或 generation.failed 事件。
幂等
重试时使用 Idempotency-Key。如果同一个 key 和同一请求体被重复发送，Rivya 可以返回已保存的公共响应，而不是创建重复任务。
如果同一个 key 搭配了不同输入，API 会返回 idempotency_conflict。