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

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 tạo nội dung 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ẻ.

Các ví dụ mô tả hợp đồng Public API v1 đã triển khai. Trước khi thử, hãy xác nhận Public API được bật cho bản triển khai và khả dụng với tài khoản. Endpoint hoặc trang mô hình được ghi nhận không tự chứng minh rằng yêu cầu chạy được ở mọi môi trường.

1. Tạo khóa API

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 máy chủ.

Các phạm vi 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 môi trường vận hành:

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 tạo nội dung.

4. Gửi tạo nội dung

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ề công khai tác vụ ID. Hãy lưu ID đó để bạn có thể thăm dò 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 điểm tín dụng

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 quyền truy cập webhook được bật cho bản triển khai và tài khoản, đồng thời máy chủ có thể nhận callback HTTPS đã ký, hãy tạo điểm cuối webhook:

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 bàn giao trước khi tin payload.

8. Tùy chọn: gửi một lượt trò chuyện

Với mô hình trò chuyện, 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": "claude-sonnet-5-chat",
    "message": "Write a concise launch plan for a new product image campaign"
  }'

Dùng session_id được trả về để tiếp tục phiên 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 máy chủ có thể dùng SDK thử nghiệm 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 truyền theo luồng phía máy chủ trong riêng tư thử nghiệm.

Trang tiếp theo

• Xác thực API

• Rivya TypeScript SDK

• Tham chiếu API mô hình

• Tạo tạo nội dung

• Chat API

• API Webhooks

• Lỗi và giới hạn API