↓
Rivya AI 文档

创建生成任务

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

最近审阅于 2026年11月11日

使用 POST /api/v1/generations 提交异步图片、视频或音频生成任务。

对 Chat 模型,请使用 Chat API。POST /api/v1/generations 不会创建 chat session 或 assistant message。

Suno Speech:场景与指定脚本

Suno Speech: prompt 在简单模式(params.customMode="false")中是场景描述,在高级模式("true")中是朗读脚本。tone、variety、vocalGender、backgroundMusic 只用于高级模式;简单模式须省略。不要在 params 中另传 script 或 prompt。

提示词单位与完整图层结果

读取 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

需要 API 已开启、账户有权限、有效 Key 具备 generations:create 或 *,并有足够积分预留。模型须在此端点可调用,检查模型参考;音频类如 Lyrics 可能返回文字。首次尝试就发送幂等键,鉴权规则见API 鉴权。

POST https://rivya.ai/api/v1/generations

必需 headers:

Authorization: Bearer rvya_sk_...
Content-Type: application/json

建议 header:

Idempotency-Key: your-unique-request-key

请求体

请求形状要求 model,prompt 与 params 在通用结构中可选,但所选模型/模式仍可要求它们或具体组合。client_request_id 是最多 128 字符的可选追踪值,不能代替幂等键。参考样例的 URL、token 和测量值须用自己的同模型原始上传响应整体替换。

{
  "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 字段里。

对 seedream-5-pro, seedream-5-pro-layer-decomposition, nano-banana-2-lite, qwen-image-3, qwen-image-3-pro,在 params.referenceMediaItems 中映射原始模型绑定上传响应:mime_type → mimeType, width → width, height → height, size_bytes → sizeBytes, image_dimensions_token → imageDimensionsToken。签名须匹配账户、模型、URL 和已上传元数据;缺失、过期、不匹配或伪造会在创建任务与预留前被拒绝。图层拆分恰好一张图片,另须满足几何限制。

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 模式。

需要已签名视频元数据的模型,在参考项映射原始上传响应:mime_type → mimeType, duration_seconds → durationSeconds, duration_token → durationToken, video_width → width, video_height → height, frames_per_second → framesPerSecond, video_bitrate_mbps → videoBitrateMbps, video_file_size_bytes → sizeBytes, video_metadata_token → videoMetadataToken。时长和视频元数据两种 token 都在创建任务及预留前验证。音频也应按模型要求保留原始 mime_type、size_bytes 及 duration_token,传为 mimeType、sizeBytes、durationToken;不要编辑签名值。

Wan 3.0 输入与预留

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 字符的提示词;首尾帧和参考场景可留空,提供时仍不超过 20,000 字符。

Wan 3.0 按所选版本与分辨率的费率,乘以“请求输出秒数+已验证参考视频秒数”后合计向上取整一次;智能时长按 30 输出秒预留。当前 Standard/Prime 各分辨率费率见Wan 3.0 API 参考。有效最终用量不超过预留时结算并退差额;用量缺失、无效或更高时保留预留为 RECONCILIATION_REQUIRED,不自动追加超额。

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

视频与音频口型同步示例

此 volcengine-video-lip-sync 示例使用一个视频与一个音频,示例测量满足限制,但占位 token 不是真实签名。请对每个参考项使用其各自对应的原始上传响应,将该项 URL、token、MIME 和测量值成组替换。

{
  "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": 13175000,
        "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",
        "sizeBytes": 1190444
      }
    ]
  }
}

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 示例

在支持 fetch 的服务端运行,先设置 RIVYA_API_KEY。检查 HTTP 结果后才能把 JSON 当成任务,不要把密钥放进浏览器。

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();
if (!response.ok) {
  throw new Error(JSON.stringify(generation.error));
}
console.log(generation.id, generation.status);

Python 示例

需安装 requests 并在服务端设置 RIVYA_API_KEY。示例 30 秒超时只限制 HTTP 等待,不设定生成时长,也不证明超时任务失败。几个示例使用同一幂等键演示同请求重试,另一笔生成须换键。

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()
if not response.ok:
    raise RuntimeError(generation.get("error"))
print(generation["id"], generation["status"])

响应

这些金额和时间只是示例,不是实时报价或实测结果。示例为提交后的 processing 任务,final_credits 初始等于预留,RESERVED 表示未结算。任务进度与积分状态分别读取,见API 积分。

保存 id 并按生成状态检查原任务;响应缺失或不明不证明任务未创建。已知 ID 时先查询。开启API Webhooks并配置有效端点后可发送签名生成事件;成功事件需结算为 SETTLED,失败事件不证明积分已退回。

{
  "id": "task_public_id",
  "status": "processing",
  "model": "z-image",
  "reserved_credits": 1,
  "final_credits": 1,
  "settlement_status": "RESERVED",
  "created_at": "2026-05-10T00:00:00.000Z",
  "updated_at": "2026-05-10T00:00:00.000Z",
  "result": null,
  "error": null
}

幂等

首次请求就带 Idempotency-Key,重试保持同账户、同 API Key、相同请求体及 client_request_id(如有)。已存响应直接重放,不新建任务,响应也可能是错误;它不是实时状态查询,仍用生成状态。

同键不同体,或原记录尚无已存响应时,均可返回 409 idempotency_conflict。结果不明时保留原键与正文,先查已有任务,保留错误 requestId;换键可能创建另一任务并再预留。幂等 header 最多保留 128 字符,超长会截断,与可选追踪字段的独立上限不同。

常见问题

client_request_id 能防止重复吗?

不能,它只是追踪字段;重放用幂等键并保持请求体不变。

换 API Key 能重放原请求吗?

不能。记录属于一个 API Key 和账户,共用余额也不使另一把 Key 取得原记录。

请求失败表示已退回积分吗?

不一定,已有 ID 时检查原任务及结算。402 insufficient_credits 表示无法覆盖初始预留,其他积分处理错误可能为 500 internal_error。格式与重试条件见API 错误与限制。

相关页面