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

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

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

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

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

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

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

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

2. أكد عنوان API الأساسي

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

https://rivya.ai

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

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. اختياري: أضف إشعارات Webhook

إذا كانت ميزة Webhook مفعلة للنشر والحساب وكان خادمك يستطيع استقبال ردود نداء موقعة عبر HTTPS، فأنشئ نقطة نهاية للـ 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 الذي يعرض مرة واحدة في الاستجابة، وتحقق من كل عملية تسليم قبل الوثوق بالحمولة.

8. اختياري: أرسل دورة محادثة

بالنسبة إلى نماذج الدردشة، استدع واجهة 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": "claude-sonnet-5-chat",
    "message": "Write a concise launch plan for a new product image campaign"
  }'

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

اختياري: استخدم الإصدار التجريبي الخاص من حزمة 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 دعما لبث المحادثة من جهة الخادم ضمن إصدار تجريبي خاص.

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