API 키를 만들고, 모델을 선택하고, 비동기 생성 작업을 제출한 뒤 선택적 SSE 스트리밍이 있는 Chat API 턴을 보내세요.

이 빠른 시작 문서는 계정 설정부터 Rivya API 생성 작업 하나까지 가는 가장 짧고 안전한 경로와 첫 Chat API 턴을 보여 줍니다.

문서와 예제에는 자리표시자 키를 사용하세요. 실제 API 키를 공개 코드, 스크린샷, 지원 티켓, 공유 문서에 붙여 넣지 마세요.

이 예시는 구현된 Public API v1 계약을 설명합니다. 테스트 전에 배포에서 Public 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

로컬호스트 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. 선택 사항: 웹훅 추가

배포와 계정에서 웹훅을 사용할 수 있고 서버가 서명된 HTTPS 콜백을 받을 수 있다면 엔드포인트를 만드세요.

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 턴 보내기

채팅 모델의 경우 POST /api/v1/generations 대신 Chat API를 호출하세요.

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 빠른 시작