创建 API Key、选择模型、提交异步生成任务，并发送一轮可选择 SSE 流式响应的 Chat API 请求。

这篇快速开始说明从账户设置到完成一条 Rivya API 生成任务的最短安全路径，也包含第一轮 Chat API 请求。

文档和示例只使用占位 key。不要把真实 API Key 粘贴到公开代码、截图、工单或共享文档里。

这些示例介绍的是已经实现的 Public API v1 合同。测试前，请确认当前部署已启用 Public API，而且你的账号可以使用它。仅有接口文档或模型页面，并不能证明请求可在所有环境中运行。

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

如果部署与账号已经开放 webhook 权限，而且你的服务端可以接收带签名的 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": "claude-sonnet-5-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 快速开始