أنشئ مفتاح API، واختر نموذجا، وأرسل مهمة توليد غير متزامنة، وأرسل دورة Chat API مع بث SSE اختياري.

يعرض هذا البدء السريع أقصر مسار آمن من إعداد الحساب إلى مهمة توليد واحدة عبر Rivya API، إضافة إلى أول دورة Chat API.

استخدم مفاتيح وهمية في الوثائق والأمثلة. لا تلصق أبدا مفتاح API حقيقيا في كود عام، أو لقطات شاشة، أو تذاكر، أو مستندات مشتركة.

1. أنشئ مفتاح API

افتح إعدادات API Keys، وأنشئ مفتاحا، وانسخ السر الكامل مرة واحدة، وخزنه في بيئة الخادم لديك.

النطاقات الأولى الموصى بها:

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

2. أكد Base URL

استخدم عنوان API الأساسي للإنتاج:

https://rivya.ai

عناوين localhost مخصصة للتطوير المحلي فقط. يجب ألا تستخدم الأمثلة العامة أسرارا محلية.

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

تعيد الاستجابة معرف مهمة عاما. خزنه حتى تتمكن من استطلاع الحالة لاحقا.

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. اختياري: أضف Webhooks

إذا كان خادمك يستطيع استقبال callbacks موقعة عبر HTTPS، فأنشئ endpoint للـ 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"]
  }'

احفظ signing_secret الذي يعرض مرة واحدة في الاستجابة، وتحقق من كل delivery قبل الوثوق بالـ payload.

8. اختياري: أرسل Chat Turn

بالنسبة إلى نماذج الدردشة، استدع Chat API بدلا من 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"
  }'

استخدم session_id العائد لمتابعة الجلسة المنشأة عبر API. يجب أن تشير مرفقات الصور إلى قيم file_id من Files API.

اختياري: استخدم TypeScript SDK Beta

يمكن لتكاملات TypeScript على الخادم استخدام 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 دعم بث Chat من جهة الخادم في private beta.

البدء السريع مع Rivya API