Rivya API

把 Rivya 的多模態模型層接進你的產品

Rivya API 讓產品團隊能以公開、基於帳戶的方式，從自己的應用呼叫 Rivya 模型。先從非同步圖片、影片和音訊任務開始，再在模型支援 Chat 時加入帶可選 SSE streaming 的 Chat API turn，並把計費留在同一個 Rivya 點數錢包內。

閱讀 API 文件建立 API Key

快速接入形態

模型層

動態目錄

計費

共用點數

首發版本

任務 + Chat

存取方式

API Key

請求方法POST

端點路徑/api/v1/generations

真實請求必須使用 Rivya API Key，並消耗帳戶點數。公開範例只使用占位密鑰，不允許匿名真實呼叫模型。

請求範例

curl https://rivya.ai/api/v1/generations \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-job-001" \
  -d '{
    "model": "z-image",
    "prompt": "Editorial product photo on a clean studio set"
  }'

回應範例

{
  "id": "task_public_id",
  "status": "queued",
  "model": "z-image",
  "reserved_credits": 20,
  "result": null,
  "error": null
}

首版能力

與 Rivya 產品保持一致的公開 API 層

這是 Rivya 的產品介面之一。它使用 Rivya model IDs、Rivya 點數、公開任務狀態，以及與模型目錄保持連動的文件。

圖片生成 API

用 prompt 和模型支援的參數提交圖片任務，再輪詢公開結果。

影片生成 API

使用與 Studio 相同的任務和點數控制，執行非同步影片任務。

音訊生成 API

透過同一個帳戶、餘額和歷史邊界，使用可由 API 存取的音訊模型。

共用點數錢包

API 呼叫和 Studio 使用會從同一個 Rivya 餘額扣除，並套用預扣點數與失敗處理。

接入路徑

從帳戶到第一個 API 請求

建立 Key

登入後開啟 Settings 裡的 API Keys，建立有 scope 的 key，並立即儲存完整 secret。

選擇模型

閱讀 API model reference，或呼叫 /api/v1/models 檢查 model IDs、參數、Chat capabilities 和 input readiness，再提交任務。

提交、輪詢或訂閱

送出帶冪等鍵的生成請求、輪詢公開任務端點、用簽名 webhooks 接收生成回呼，或送出帶可選 SSE streaming 的 Chat API turn。

版本邊界

範圍清楚，不暗示尚未完成的能力

Landing page 可以提到未來方向，但目前產品文案不能暗示尚未完成的 API 已經上線。

Chat API

已開放

已支援 non-streaming 與 SSE streaming turns、API-created sessions、帳戶點數，以及可選的 Files API 圖片附件。

Files API

已開放

已支援參考圖片、影片和音訊上傳。當模型頁要求 params.referenceMediaItems 時，請先透過 Files API 上傳素材。

User webhooks

已開放

已提供給正式環境整合，用於接收生成任務成功或失敗的簽名回呼。

線上偵錯器

先預覽請求，再用你的 API Key 執行真實請求

偵錯器會為所有訪客從 mock 模式開始。Generation selector 只列出不需要上傳檔案即可測試的非 Chat 模型；Files panel 則讓已登入使用者以臨時 API Key 測試 /api/v1/files。Chat 範例放在 API 文件中。

帳戶狀態

正在檢查帳戶

Active key prefix

請先建立 key

目前點數

登入後查看

Mock 預覽真實 Public API沒有 active API Key

Mock 模式不會呼叫模型，也不會消耗點數。

模型

Idempotency key

Client request id

提示詞

API Key

只為這次請求貼上 key。重新整理後，偵錯器不會保留完整 key。

Files API 上傳測試

透過 POST /api/v1/files 上傳參考媒體，再把回傳的 URL 和 duration token 放入支援參考輸入模型的 params.referenceMediaItems。

Mock 不上傳檔案真實請求使用 /api/v1/files

參考模型

檔案類型

參考檔案

所選模型會決定允許的 MIME type、大小和時長規則。真實上傳需要你的臨時 API Key，並可能呼叫真正的上傳服務。

建立 API Key 閱讀 API 文件

請求預覽

{
  "model": "z-image",
  "prompt": "乾淨棚拍場景中的編輯風產品照片",
  "params": {
    "aspect_ratio": "1:1"
  }
}

回應

{
  "id": "mock_task_001",
  "status": "queued",
  "model": "z-image",
  "reserved_credits": 1,
  "final_credits": 0,
  "result": null,
  "error": null
}

Files API 回應

{
  "id": "file_mock_001",
  "object": "file",
  "kind": "image",
  "file_name": "reference.png",
  "mime_type": "image/png",
  "size_bytes": 245760,
  "url": "https://media.example/reference.png",
  "duration_seconds": null,
  "duration_token": null,
  "created_at": "2026-05-11T00:00:00.000Z",
  "expires_at": null
}

生成參數

{
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://media.example/reference.png",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png"
      }
    ]
  }
}

任務狀態

預計基礎點數

狀態

queued