API key를 만들고, model을 선택하고, 비동기 generation job을 제출한 뒤 optional SSE streaming이 있는 Chat API turn을 보내세요.

이 quickstart는 account setup에서 Rivya API generation job 하나까지 가는 가장 짧고 안전한 경로와 첫 Chat API turn을 보여 줍니다.

docs와 examples에는 placeholder keys를 사용하세요. real API key를 public code, screenshots, tickets, shared documents에 붙여 넣지 마세요.

1. API Key 만들기

API Keys settings를 열고 key를 만든 뒤 full secret을 한 번 복사하여 server-side environment에 저장하세요.

권장 first scopes:

models:read
generations:create
generations:read
files:create
files:read
credits:read
webhooks:manage
chat:create
chat:read

2. Base URL 확인

production API base URL을 사용하세요.

https://rivya.ai

Localhost URLs는 local development 전용입니다. Public examples는 local secrets를 사용하면 안 됩니다.

3. Models 나열

curl https://rivya.ai/api/v1/models

generation을 만들 때 response의 id field를 model 값으로 사용하세요.

4. Generation 제출

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"
  }'

response는 public task ID를 반환합니다. 나중에 status를 poll할 수 있도록 저장하세요.

5. Status Poll 하기

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

Status values:

queued
processing
succeeded
failed

6. Credits 확인

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

테스트 전후에 현재 account balance를 확인할 때 사용하세요.

7. Optional: Webhooks 추가

서버가 signed HTTPS callbacks를 받을 수 있다면 webhook endpoint를 만드세요.

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"]
  }'

response의 one-time signing_secret을 저장하고, payload를 신뢰하기 전에 every delivery를 검증하세요.

8. Optional: Chat Turn 보내기

chat models의 경우 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": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign"
  }'

반환된 session_id를 사용해 API가 만든 session을 이어가세요. 이미지 첨부는 Files API file_id 값을 참조해야 합니다.

Optional: TypeScript SDK Beta 사용

Server-side TypeScript integrations는 local SDK beta를 사용할 수 있습니다.

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에는 private beta의 server-side Chat streaming support가 포함되어 있습니다.

Rivya API 빠른 시작