1. 创建 API Key

打开 API Keys 设置，创建 key，复制一次完整密钥，并把它保存到服务端环境变量中。

建议首个 key 使用这些 scope：

models:read
generations:create
generations:read
files:create
files:read
credits:read
webhooks:manage
chat:create
chat:read

2. 确认 Base URL

使用生产 API base URL：

https://rivya.ai

localhost URL 只用于本地开发。公开示例不应使用本地 secret。

3. 查询模型

curl https://rivya.ai/api/v1/models

响应里的 id 字段就是创建生成任务时的 model 值。

4. 提交生成任务

curl https://rivya.ai/api/v1/generations \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-001" \
  -d '{
    "model": "z-image",
    "prompt": "A clean editorial product image on a soft studio background"
  }'

响应会返回公开任务 ID。保存这个 ID，后续用它查询状态。

5. 轮询状态

curl https://rivya.ai/api/v1/generations/task_public_id \
  -H "Authorization: Bearer rvya_sk_..."

状态值包括：

queued
processing
succeeded
failed

6. 查询积分

curl https://rivya.ai/api/v1/credits \
  -H "Authorization: Bearer rvya_sk_..."

测试前后都可以用它确认当前账户余额。

7. 可选：添加 Webhooks

如果你的服务端可以接收带签名的 HTTPS 回调，可以创建 webhook endpoint：

curl https://rivya.ai/api/v1/webhooks \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://example.com/rivya/webhook",
    "event_types": ["generation.succeeded", "generation.failed"]
  }'

请保存响应中只展示一次的 signing_secret，并在信任 payload 前校验每次投递。

8. 可选：发送 Chat Turn

对 Chat 模型，请调用 Chat API，不要调用 POST /api/v1/generations：

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-chat-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign"
  }'

使用返回的 session_id 继续 API 创建的 session。图片附件必须引用 Files API 返回的 file_id。

可选：使用 TypeScript SDK Beta

服务端 TypeScript 集成可以使用本地 SDK beta：

import { RivyaClient } from "@rivya/sdk";

const rivya = new RivyaClient({
  apiKey: process.env.RIVYA_API_KEY
});

const generation = await rivya.generations.create({
  model: "z-image",
  prompt: "A clean editorial product image on a soft studio background"
});

接入前请阅读 Rivya TypeScript SDK。当前 private beta SDK 包含服务端 Chat streaming 支持。

Rivya API 快速开始