Rivya API v1 스키마 원본, 호환성 규칙, 공개 필드 및 읽기 전용 OpenAPI JSON 계약을 확인하세요.

Rivya API v1은 다음 위치에서 읽기 전용 스키마 계약을 제공합니다.

https://rivya.ai/api/v1/openapi.json

이 경로는 공개 계약 출력입니다. 사용자 세션 데이터를 읽거나 모델 작업을 제출하지 않으며 비공개 계정 데이터도 노출하지 않습니다.

계약 원본

계약은 다음 항목에서 파생됩니다.

공개 API 요청 스키마
공개 오류 코드
공개 API 모델 참고 계층
/api/v1/models와 동일한 모델 카탈로그

모델 목록은 동적으로 구성됩니다. 수동으로 작성한 모델 수에 의존하는 연동을 구현하지 마세요.

버전 정책

현재 API 버전은 v1입니다.

하위 호환 변경에는 다음이 포함될 수 있습니다.

/api/v1/models에 모델 추가
선택적 응답 필드 추가
모델에 선택적 요청 매개변수 추가
새 공개 오류 코드 추가

호환성을 깨는 변경에는 새 버전 또는 문서화된 마이그레이션 경로가 필요합니다.

공개 필드 경계

공개 스키마 필드는 공개 이름을 사용합니다.

id
status
model
session_id
message
usage
reserved_credits
final_credits
created_at
updated_at
result
error

내부 작업 저장소 필드에 의존하지 마세요. 해당 필드는 공개 계약의 일부가 아닙니다.

요청 스키마

POST /api/v1/generations는 다음 필드를 받습니다.

model: 필수 공개 모델 ID
prompt: 선택적 문자열이며 많은 모델에서 필수입니다.
params: 모델별 매개변수를 담는 선택적 객체
client_request_id: 자체 추적 ID로 사용할 선택적 문자열

모델별 params는 모델 API 참고 문서를 확인하세요.

/api/v1/files가 반환한 참조 미디어는 params.referenceMediaItems 안에 넣습니다. 스키마에는 url, kind, 선택적 name, 선택적 mimeType, 선택적 durationSeconds / durationToken, 선택적 width / height / sizeBytes / imageDimensionsToken, 선택적 framesPerSecond / videoBitrateMbps / videoMetadataToken이 정의되어 있습니다. 모든 Image5, Grok Imagine Image 2.0 및 Wan 3.0 참조 이미지는 원래의 모델 지정 업로드 응답에 포함된 서명 이미지 토큰과 연결된 바이트 크기를 요구하며, Layer Decomposition은 문서화된 기하 범위도 적용합니다. Video8 및 Wan 3.0 참조 비디오는 모두 원래의 모델 지정 업로드 응답에 포함된 서명 재생 시간 토큰과 서명 비디오 메타데이터를 요구합니다. Rivya는 POST /api/v1/generations에서 최상위 files 필드를 받지 않습니다.

POST /api/v1/files는 file, kind, 선택적 model, 선택적 client_request_id가 포함된 multipart form data를 받습니다. 응답은 size_bytes, nullable 이미지 크기, image_dimensions_token, nullable video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, video_metadata_token을 포함하는 PublicApiFile입니다. GET /api/v1/files/{fileId}는 API 계정이 소유한 파일의 공개 메타데이터를 반환하지만, 저장되지 않은 서명 메타데이터 토큰은 null일 수 있으므로 파일을 다시 업로드해 새 토큰을 받아야 합니다.

video_metadata_token은 API 계정, 대상 모델, URL, MIME 형식, 크기, 프레임 속도, 비트레이트 및 업로드 바이트 크기에 바인딩됩니다. 이 토큰은 duration_token을 대체하지 않습니다. 두 계약을 모두 사용하는 Video8 및 Wan 3.0 참조 비디오는 두 토큰을 모두 제공해야 합니다. Wan 3.0 오디오 재생 시간 토큰도 MIME 형식과 업로드 바이트 크기에 바인딩됩니다.

wan-3-0-video의 params에는 seedance_scene, variant, resolution, aspect_ratio, duration, audio, seed, referenceMediaItems만 사용할 수 있습니다. 텍스트, 프레임 및 참조 장면은 서로 배타적입니다. 지능형 재생 시간은 -1이며 30초를 예약하고 참조 비디오와 함께 사용할 수 없습니다. 임의의 키, 서명되지 않은 미디어, 파일 기반 비디오 생성 및 링크 기반 비디오 생성의 단축 경로는 모두 실패 시 차단 원칙에 따라 거부됩니다.

POST /api/v1/chat/completions는 model, message, 선택적 session_id, 선택적 제어값, 선택적 Files API file_id 첨부 및 선택적 client_request_id를 받습니다. 완성된 비스트리밍 어시스턴트 메시지 하나를 반환합니다.

POST /api/v1/chat/completions/stream은 동일한 요청 스키마를 받고 session.created, message.delta, message.completed, usage.completed, heartbeat, error, done 이벤트가 포함된 text/event-stream을 반환합니다. Chat API v1은 원시 messages 배열을 받지 않습니다.

응답 스키마

OpenAPI 출력에는 다음 공개 응답 형식이 정의되어 있습니다.

GET /api/v1/models용 ModelList
모델 선택 및 매개변수 폼용 PublicApiModel과 ModelParam
POST /api/v1/files 및 GET /api/v1/files/{fileId}용 PublicApiFile
파일 기반 생성 매개변수용 ReferenceMediaItem
생성 및 상태 응답용 PublicGeneration
완료된 작업용 GenerationResult와 GenerationError
Chat API용 ChatCompletionRequest, ChatCompletion, ChatSession, ChatMessage, ChatUsage, ChatCredits 및 채팅 스트림 이벤트 스키마
GET /api/v1/credits용 CreditBalance
서명된 API Webhook용 WebhookEndpoint, WebhookEvent, WebhookDelivery, WebhookTestResult
안정적인 오류 응답용 PublicApiError

이 스키마는 클라이언트 검증과 내부 연동 테스트에 사용할 수 있습니다. TypeScript SDK 베타도 이 스키마 범위 안에서 유지됩니다.

예시 관리 원칙

이 문서의 curl, JavaScript 및 Python 예시는 스키마와 동일한 공개 필드 이름을 사용합니다.

Authorization: Bearer rvya_sk_...
Idempotency-Key
model
prompt
message
session_id
params
client_request_id

채팅 예시는 다음 항목도 사용합니다.

chat:create
chat:read
file_id

Webhook 예시는 다음 항목도 사용합니다.

Rivya-Webhook-Signature
Rivya-Webhook-Timestamp
webhooks:manage

모델 매개변수가 바뀌면 모델 카탈로그와 공개 직렬화 계층을 먼저 업데이트하세요. 문서와 디버거는 별도 표를 복사하지 말고 동일한 공개 계층을 사용해야 합니다.

OpenAPI와 스키마 계약