↓
Rivya AI 文件

Rivya API 快速開始

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

最近審閱於 2026年11月5日

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

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

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

1. 建立 API 金鑰

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

設定頁建立的新 Key 固定授予下列全部九項權限,沒有權限選擇器;無法直接編輯舊 Key 的權限。

  • 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. 列出模型

模型清單公開,不需 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,請妥善儲存,以便稍後輪詢狀態。

6. 輪詢狀態

queued 或 processing 時繼續檢查原任務;查詢錯誤不等於生成失敗。保存任務 ID,依生成狀態指南讀取任務與結算。

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

狀態值包括:

  • queued

  • processing

  • succeeded

  • failed

7. 選用:新增 Webhooks

管理端點需要 webhooks:manage 且 Webhook 功能已啟用。傳送、簽章與事件訂閱條件見API 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_capabilities,僅在模型支援圖片附件時引用 file_id;目前可用的 Claude 模型僅接受文字。欄位與串流規則見聊天 API。

對於聊天模型,請呼叫 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 測試版

SDK 是尚未發布至公開 npm 的私有測試版,需要已獲存取權的原始碼或建置套件,並確保伺服器可解析 @rivya/sdk;沒有存取權時直接使用 HTTP 端點。

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

下一頁