↓
Rivya AI 文档

创建生成任务

使用 model、prompt、params、Idempotency-Key 和公共响应字段提交 Rivya API 异步生成任务。

最近审阅于 2026年8月25日

使用 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：必填，公共模型 ID

  • prompt：提示词文本，很多模型实际需要

  • params：模型专属参数对象

  • client_request_id：可选，来自你系统的追踪 ID

模型专属 params 见 模型 API Reference。

参考文件放入 Params

对支持上传参考素材的模型，先调用 Files API。然后把上传结果放入模型 params；生成请求不要新增顶层 files 字段。

新集成优先使用 params.referenceMediaItems：

{
  "model": "nano-banana-2-lite",
  "prompt": "Restyle this product photo for a clean editorial catalog page",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png",
        "width": 1024,
        "height": 1024,
        "sizeBytes": 482314,
        "imageDimensionsToken": "image_dimensions_token_from_files_api"
      }
    ]
  }
}

如果音频或视频输入需要时长校验，请把 /api/v1/files 返回的 duration_token 放在对应 referenceMediaItems 条目的 durationToken 字段里。

每张 Image5 参考图都必须携带原始模型绑定 Files API 响应中的 width、height、size_bytes 和 image_dimensions_token，并分别传为 width、height、sizeBytes 和 imageDimensionsToken。token 缺失、过期、绑定失配或由客户端自行构造时，会在创建任务和预留积分前失败。图层拆分还要求恰好一张图片，并满足其文档规定的几何边界。

Grok Imagine Image 2.0 使用相同的已签名图片元数据边界。文本生成图片时不要发送参考素材项；标准图片编辑时发送 1–5 个唯一的已签名 JPEG、PNG 或 WebP 素材项。文本生成图片接受 1:1、2:3、3:2、16:9 或 9:16；图片编辑额外接受 auto。Segment Map 和 Segment Edit 不是可调用的 Public API 模式。

每个 Video8 参考视频都必须携带原始模型绑定响应中的 duration_seconds、duration_token、video_width、video_height、frames_per_second、video_bitrate_mbps、video_file_size_bytes 和 video_metadata_token。请分别传为 durationSeconds、durationToken、width、height、framesPerSecond、videoBitrateMbps、sizeBytes 和 videoMetadataToken。两个签名 token 都会在创建任务和预留积分前完成验证。

Wan 3.0 使用三个互斥的 seedance_scene 值。text 不接受上传素材；frames 必须有一张首帧图，并可选一张尾帧图；reference 接受由图片、视频和音频组成的已签名素材组合，但音频不能是唯一素材。所有参考 URL 都必须来自原始的模型绑定 Files API 上传。文件转视频和链接转视频快捷模式仍不可用。

variant 可设为 standard 或 prime，resolution 可设为 480P、720P 或 1080P，aspect_ratio 可设为 adaptive、16:9、4:3、1:1、3:4 或 9:16。duration 接受 2–30 的整数，或用 -1 表示智能时长；audio 控制是否生成模型音频，seed 接受 0–2147483647。去除首尾空白后的提示词必须为 1–20,000 个字符。

Wan 3.0 Standard 在 480P、720P、1080P 下分别按每个请求输出秒 8、16、32 积分预留；Prime 分别按每秒 12.2、25.2、50.4 积分预留。Rivya 只对合计预留额统一向上取整一次；智能时长按 30 秒预留。有效且不超过预留额的实际用量会完成结算并退还差额；实际用量缺失、无效或高于预留额时保留原预留并进入对账，不会暗中追加扣点。

Wan 3.0 参考场景最多可发送 10 张图片、5 个视频和 5 个音频。单个视频或音频时长均须为 1–15 秒，视频与音频各自还有独立的 15 秒合计上限。duration=-1 不能与参考视频同时使用；使用视频输入时，已验证的输入视频秒数加请求输出秒数不得超过 30。

下面是 Video8 视频加音频口型同步任务示例：

{
  "model": "volcengine-video-lip-sync",
  "prompt": "",
  "params": {
    "mode": "lite",
    "separate_vocal": "false",
    "open_scenedet": "false",
    "referenceMediaItems": [
      {
        "url": "https://.../source.mov",
        "kind": "video",
        "name": "source.mov",
        "mimeType": "video/quicktime",
        "durationSeconds": 12.4,
        "durationToken": "duration_token_from_files_api",
        "width": 1920,
        "height": 1080,
        "framesPerSecond": 30,
        "videoBitrateMbps": 8.5,
        "sizeBytes": 26214400,
        "videoMetadataToken": "video_metadata_token_from_files_api"
      },
      {
        "url": "https://.../dialogue.wav",
        "kind": "audio",
        "name": "dialogue.wav",
        "mimeType": "audio/wav",
        "durationSeconds": 12.4,
        "durationToken": "audio_duration_token_from_files_api"
      }
    ]
  }
}

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。

相关页面

模型 API 参考

查询 Rivya API 模型 ID、可用状态、支持模式、参数表、提示词上限、参考素材规则和模型详情链接。

Chat API

使用 Rivya Chat API 发送非流式或 SSE 流式对话，继续由 API 创建的会话，添加 file_id 图片附件，并按 token 用量结算积分。

目录

Endpoint
请求体
参考文件放入 Params
curl 示例
JavaScript 示例
Python 示例
响应
幂等
相关页面