Tạo API key, chọn mô hình, gửi job generation bất đồng bộ và gửi một lượt Chat API với SSE streaming tùy chọn.

Hướng dẫn nhanh này chỉ ra đường đi an toàn ngắn nhất từ thiết lập tài khoản đến một job generation Rivya API, kèm lượt Chat API đầu tiên.

Chỉ dùng key placeholder trong tài liệu và ví dụ. Không bao giờ dán API key thật vào mã công khai, ảnh chụp màn hình, ticket hoặc tài liệu chia sẻ.

1. Tạo API key

Mở cài đặt API Keys, tạo key, sao chép full secret một lần và lưu nó trong môi trường phía server.

Các scope khuyến nghị cho key đầu tiên:

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

2. Xác nhận Base URL

Dùng API base URL production:

https://rivya.ai

Localhost URL chỉ dành cho phát triển cục bộ. Ví dụ công khai không nên dùng secret cục bộ.

3. Liệt kê mô hình

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

Dùng trường id trong phản hồi làm giá trị model khi tạo generation.

4. Gửi 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"
  }'

Phản hồi trả về public task ID. Hãy lưu ID đó để bạn có thể poll trạng thái sau.

5. Poll trạng thái

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

Các giá trị trạng thái là:

queued
processing
succeeded
failed

6. Kiểm tra credits

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

Dùng lệnh này để xác nhận số dư tài khoản hiện tại trước hoặc sau khi kiểm thử.

7. Tùy chọn: thêm Webhooks

Nếu server của bạn có thể nhận callback HTTPS có chữ ký, hãy tạo một 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"]
  }'

Lưu signing_secret chỉ hiển thị một lần trong phản hồi và xác minh mọi lần delivery trước khi tin payload.

8. Tùy chọn: gửi một lượt Chat

Với mô hình chat, hãy gọi Chat API thay vì POST /api/v1/generations:

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

Dùng session_id được trả về để tiếp tục session do API tạo. Ảnh đính kèm phải tham chiếu giá trị file_id của Files API.

Tùy chọn: dùng TypeScript SDK Beta

Tích hợp TypeScript phía server có thể dùng SDK beta cục bộ:

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"
});

Đọc Rivya TypeScript SDK trước khi áp dụng. SDK hiện bao gồm hỗ trợ Chat streaming phía server trong private beta.

Bắt đầu nhanh với Rivya API