API 模型
列出 Rivya API 模型,了解模型 ID、分類、提示詞限制、參考媒體、就緒狀態與 Files API 依賴。
最近審閱於 2026年11月11日
使用 GET /api/v1/models 列出 Rivya 模型及其 Public API 可用狀態。
curl https://rivya.ai/api/v1/models這個端點是公開且唯讀的。它會回傳與 API 文件和線上偵錯器使用的相同公開模型清單,包含尚未完全開放呼叫的模型。
可用 locale 查詢參數要求本地化顯示名稱與參數標籤;模型 ID、參數鍵、選項值與狀態不變。不支援的語言回退英文。此清單不需 Key,線上偵錯器僅提供其中部分模型;列入目錄不授予呼叫資格。
Suno Speech:場景與指定腳本
Suno Speech: prompt 在簡單模式(params.customMode="false")中是場景描述,在進階模式("true")中是朗讀腳本。tone、variety、vocalGender、backgroundMusic 只用於進階模式;簡單模式須省略。不要在 params 中另傳 script 或 prompt。
提示詞單位與完整圖層結果
讀取 GET /api/v1/models 時,請將 prompt_length_unit 與 max_prompt_length 一起使用。utf8_bytes 計算原文的 UTF-8 位元組,包含空格與換行;utf16_code_units 計算 JavaScript 的 UTF-16 程式碼單元。上限為 null 不代表文字不限長或可以不填。Gemini TTS 使用位元組單位。
已完成的圖層拆分結果可在完整的 result.urls 之外提供 result.layers。請保留每層回傳的 z_index、URL、尺寸、名稱、說明與邊界框,索引零是底圖。TypeScript SDK 已提供這些欄位。參考檔案須依所選模型上傳,並傳回原始簽章中繼資料;單獨宣告尺寸或時長不能代替核驗。
回應格式
以下僅展示 z-image 的部分欄位,並非完整回應;即時回應另含價格與媒體限制,請以即時值為準。
{
"object": "list",
"data": [
{
"id": "z-image",
"display_name": "Z-Image",
"category": "image",
"runtime": "async_task",
"base_credits": 1,
"billing_type": "FIXED",
"supported_modes": ["text-to-image"],
"max_prompt_length": 1000,
"reference_media": null,
"params": [
{
"key": "aspect_ratio",
"type": "select",
"label": "Aspect ratio",
"required": false,
"default_value": "1:1",
"options": [
{ "value": "1:1", "label": "1:1" },
{ "value": "4:3", "label": "4:3" },
{ "value": "3:4", "label": "3:4" },
{ "value": "16:9", "label": "16:9" },
{ "value": "9:16", "label": "9:16" }
]
}
],
"supports_direct_generation": true,
"api_status": "available",
"api_input_status": "available_text",
"supported_api_inputs": ["text"],
"requires_files_api": false,
"requires_upload_for_modes": [],
"url_input_supported": false,
"file_kinds": [],
"chat_capabilities": null,
"notices": []
}
]
}對於非同步生成模型,請使用 id 作為 model 值,並放入 POST /api/v1/generations。對於聊天模型,請使用 POST /api/v1/chat/completions 並檢查 chat_capabilities。
讀取模型欄位
id 用於請求,display_name 僅供顯示;category 表示類別,runtime 區分非同步生成與聊天。supported_modes 是 Rivya 已對應的流程,不代表服務商的全部功能。
max_prompt_length 為 null 不代表提示詞無長度限制或可省略。max_images、max_videos、max_audios 與 reference_media 是設定的媒體限制;null 不代表無上限,也不能據此推斷必要數量或可組合類型。
params 包含鍵、類型、標籤、預設值與選項。數值參數可帶 min、max、step,文字參數可帶 max_length。傳送選項的 value,不要傳送顯示標籤,並遵守 hide_when_modes。required: false 仍可能有模式條件;完整的輸入組合、中繼資料與驗證以模型參考為準。
base_credits、billing_type 與 pricing 描述目前計費設定,最終點數遵循模型的計費與結算規則。notices 是補充說明,應搭配模型參考與端點文件閱讀。
可用狀態
檢查 api_status 後再選擇新請求:
available:可用於公開 API,仍須檢查supports_direct_generation、runtime與輸入要求。temporarily_unavailable:目前無法透過公開 API v1 呼叫。studio_only:不能透過公開 API v1 呼叫;實際工作台可用性以目前產品頁為準。coming_soon:僅供探索,不能提交生成或聊天請求。
不可呼叫項目的執行類型、計費、價格、提示詞上限、媒體上限及聊天能力為 null,supported_modes 與 params 為空。這不代表解鎖模型或免除輸入限制。
輸入準備狀態
api_input_status 是輸入方式摘要,不能取代驗證:available_text 依模型使用 prompt、params.dialogue 或聊天 message;available_url_input 使用模型要求的 URL 參數;partial_requires_files 同時有文字或 URL 路徑及檔案模式,應檢查 requires_upload_for_modes;requires_files_api 依賴參考檔案,須先上傳。
supported_api_inputs 用 text、url、file 概括輸入類型,file_kinds 表示可接收的媒體種類,並不允許任意組合。需要參考檔案的模式應先使用檔案 API。
模型要求簽章媒體中繼資料時,保留原始、與模型綁定的上傳回應;單獨 URL 或後續 GET /api/v1/files/{fileId} 中繼資料可能缺少必要 token 與已驗證欄位。url_input_supported: true 也不免除格式、歸屬、時長或簽章驗證。
聊天模型的 chat_capabilities 描述一般回應、SSE、網路搜尋、圖片 file_id、思考設定支援及推理強度。傳送選填欄位前檢查目前值;服務商支援不代表 Rivya 已啟用。
模型數量政策
公開模型清單會隨著 Rivya 新增、移除或限制模型而改變。
不要在整合中依賴硬編碼的模型數量。請一律讀取 /api/v1/models 或動態 模型 API 參考。
即時 OpenAPI 契約分別列出新生成、聊天與上傳請求可用的模型 ID。已儲存的生成與聊天回應仍用字串 model,可保留歷史 ID;不要因舊模型不在目前請求列舉中就拒絕歷史回應。
相關頁面
即將推出的唯讀探索項目
coming_soon:模型只供探索,不能提交至生成或 Chat API。此類唯讀項目回傳supports_direct_generation: false,執行方式、帳務與定價均為null,supported_modes與params為空。發送請求時請選擇api_status: available的模型。
模型可用性問題
為什麼清單中的模型不在請求列舉中?
公開清單包含暫不可用與 Coming Soon 項目;請求列舉僅列出對應端點可用的模型,因此生成、聊天與檔案上傳的列舉不同。選擇端點前先檢查可用性與輸入欄位。
notices 為空是否代表沒有限制?
不是。notices 僅是補充說明,不是完整驗證清單。可用模型也可能要求特定檔案組合、格式或簽章 token,應遵循模型參考及端點文件。
