1. 建立 API Key

開啟 API Keys 設定，建立 key，只複製一次完整 secret，並將它存放在伺服器端環境中。

建議第一組 scopes：

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

2. 確認 Base URL

使用 production API base URL：

https://rivya.ai

Localhost URLs 只用於本機開發。公開範例不應使用本機 secrets。

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"
  }'

回應會回傳公開 task 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 callbacks，請建立 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 前驗證每次 delivery。

8. 選用：送出 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 建立的工作階段。圖片附件必須引用 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。SDK 在 private beta 中包含伺服器端 Chat 串流支援。

Rivya API 快速開始