建立 API 金鑰、選擇模型、提交非同步生成任務，並送出可選擇 SSE 串流的 Chat API 回合。

這份快速開始說明從帳號設定到完成一個 Rivya API 生成任務的最短安全路徑，並包含第一個 Chat API 回合。

文件和範例應使用預留位置金鑰。切勿把真實的 API 金鑰貼到公開程式碼、截圖、客服單或共用文件中。

這些範例介紹的是已實作的公開 API v1 規格。測試前，請確認目前部署已啟用公開 API，而且你的帳號可以使用。只有端點文件或模型頁面，並不能證明請求可在所有環境執行。

1. 建立 API 金鑰

開啟 API 金鑰設定，建立金鑰。完整金鑰只會顯示一次，請立即複製並存放在伺服器端環境中。

第一組金鑰建議包含以下權限範圍：

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

2. 確認基底 URL

請使用正式環境的 API 基底 URL：

https://rivya.ai

localhost URL 只用於本機開發，公開範例不應包含本機金鑰。

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，請妥善儲存，以便稍後輪詢狀態。

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 端點：

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，並在信任傳來的內容前驗證每次傳送的簽章。

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": "claude-sonnet-5-chat",
    "message": "Write a concise launch plan for a new product image campaign"
  }'

使用回傳的 session_id 繼續 API 建立的工作階段。圖片附件必須引用 Files API 的 file_id 值。

選用：使用 TypeScript SDK 測試版

伺服器端 TypeScript 整合可以使用本機 SDK 測試版：

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 支援伺服器端 Chat 串流。

Rivya API 快速開始