Rivya API 快速开始
创建 API Key、选择模型、提交异步生成任务,并发送一轮可选择 SSE 流式响应的 Chat API 请求。
最近审阅于 2026年11月5日
这篇快速开始说明从账户设置到完成一条 Rivya API 生成任务的最短安全路径,也包含第一轮 Chat API 请求。
文档和示例只使用占位 key。不要把真实 API Key 粘贴到公开代码、截图、工单或共享文档里。
这些示例介绍的是已经实现的 Public API v1 合同。测试前,请确认当前部署已启用 Public API,而且你的账号可以使用它。仅有接口文档或模型页面,并不能证明请求可在所有环境中运行。
1. 创建 API Key
打开 API Keys 设置,创建 key,复制一次完整密钥,并把它保存到服务端环境变量中。
设置页创建的新 Key 固定授予下列全部九项权限,没有权限选择器;不能直接编辑旧 Key 的权限。
models:readgenerations:creategenerations:readfiles:createfiles:readcredits:readwebhooks:managechat:createchat:read
2. 确认 Base URL
使用生产 API base URL:
https://rivya.ailocalhost URL 只用于本地开发。公开示例不应使用本地 secret。
3. 查询模型
模型列表公开,无需 Key。先检查 api_status: available、输入准备状态及所需模式;列出不代表可调用,聊天模型应使用聊天端点。
curl https://rivya.ai/api/v1/models响应里的 id 字段就是创建生成任务时的 model 值。
4. 查询积分
curl https://rivya.ai/api/v1/credits \
-H "Authorization: Bearer rvya_sk_..."测试前后都可以用它确认当前账户余额。
5. 提交生成任务
受理不等于完成。首尝试即携带 Idempotency-Key;重试同一请求须保持同一 API Key 和请求体,另一笔生成用新幂等键。
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,后续用它查询状态。
6. 轮询状态
queued 或 processing 时继续检查原任务;查询错误不等于生成失败。保存任务 ID,按生成状态指南读取任务及结算。
curl https://rivya.ai/api/v1/generations/task_public_id \
-H "Authorization: Bearer rvya_sk_..."状态值包括:
queuedprocessingsucceededfailed
7. 可选:添加 Webhooks
管理端点需要 webhooks:manage 且 Webhook 功能已开启。投递、签名及事件订阅条件见API 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_capabilities,仅在模型支持图片附件时引用 file_id;当前可用的 Claude 模型只接受文字。字段与串流规则见聊天 API。
对 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
SDK 是未发布到公共 npm 的私有测试版,需要已获访问的源码或构建包,并确保服务端可解析 @rivya/sdk;没有访问权限时直接使用 HTTP 端点。
服务端 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 支持。
