Надсилайте асинхронні задачі генерації Rivya API з model, prompt, params, ключем ідемпотентності та публічними полями відповіді.

Використовуйте POST /api/v1/generations, щоб надіслати асинхронну задачу генерації зображення, відео або аудіо.

Для chat-моделей використовуйте Chat API. POST /api/v1/generations не створює чат-сесії або повідомлення асистента.

Endpoint

POST https://rivya.ai/api/v1/generations

Обов'язкові заголовки:

Authorization: Bearer rvya_sk_...
Content-Type: application/json

Рекомендований заголовок:

Idempotency-Key: your-unique-request-key

Тіло запиту

{
  "model": "z-image",
  "prompt": "A clean editorial product image on a soft studio background",
  "params": {
    "aspect_ratio": "1:1"
  },
  "client_request_id": "order-123-preview"
}

Поля:

model: обов'язковий публічний ID моделі
prompt: текст prompt, потрібний багатьом моделям
params: об'єкт параметрів, специфічних для моделі
client_request_id: необов'язковий trace ID із вашої системи

Читайте Model API Reference для params, специфічних для моделі.

Референс-файли в params

Для моделей, які приймають завантажені референс-медіа, спочатку викличте Files API. Потім передайте результат завантаження через params моделі; не додавайте поле верхнього рівня files до запиту генерації.

Для нових інтеграцій використовуйте params.referenceMediaItems:

{
  "model": "nano-banana-2-lite",
  "prompt": "Restyle this product photo for a clean editorial catalog page",
  "params": {
    "referenceMediaItems": [
      {
        "url": "https://...",
        "kind": "image",
        "name": "reference.png",
        "mimeType": "image/png",
        "width": 1024,
        "height": 1024,
        "sizeBytes": 482314,
        "imageDimensionsToken": "image_dimensions_token_from_files_api"
      }
    ]
  }
}

Для аудіо- або відеовхідних даних, які потребують перевірки тривалості, додайте duration_token, повернений /api/v1/files, як durationToken у відповідний елемент referenceMediaItems.

Кожне референс-зображення для Image5 потребує width, height, size_bytes та image_dimensions_token з початкової відповіді Files API, прив'язаної до моделі. У запиті передайте їх як width, height, sizeBytes та imageDimensionsToken. Відсутній, прострочений, невідповідний або вигаданий клієнтом токен призводить до відмови ще до створення задачі й резервування кредитів. Для Layer Decomposition додатково потрібне рівно одне зображення в межах задокументованих геометричних обмежень.

Grok Imagine Image 2.0 використовує ті самі правила для підписаних метаданих зображення. Для перетворення тексту на зображення не надсилайте жодних референс-елементів; для стандартного редагування зображення надсилайте від одного до п'яти унікальних підписаних елементів JPEG, PNG або WebP. Перетворення тексту на зображення підтримує 1:1, 2:3, 3:2, 16:9 або 9:16; редагування зображення додатково підтримує auto. Режими Segment Map і Segment Edit не можна викликати через Public API.

Кожне референс-відео Video8 потребує duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes та video_metadata_token з початкової відповіді, прив'язаної до моделі. Передайте їх як durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes та videoMetadataToken. Обидва підписані токени перевіряються до створення задачі й резервування кредитів.

Wan 3.0 використовує три взаємовиключні значення seedance_scene. text не приймає завантажених медіа; frames вимагає одне перше зображення й дозволяє одне необов'язкове останнє зображення; reference приймає підписаний набір зображень, відео й аудіо, але аудіо не може бути єдиним медіа. Усі URL референсів мають походити з початкових завантажень Files API, прив'язаних до моделі. Спрощені режими file-to-video і link-to-video залишаються недоступними.

Установіть variant як standard або prime, resolution як 480P, 720P або 1080P, а aspect_ratio як adaptive, 16:9, 4:3, 1:1, 3:4 або 9:16. duration приймає цілі числа від 2 до 30 або -1 для розумної тривалості; audio керує аудіо, яке створює модель, а seed приймає значення від 0 до 2147483647. Очищений від зайвих пробілів prompt має містити 1–20 000 символів.

Wan 3.0 Standard резервує 8, 16 або 32 кредити за кожну запитану секунду результату в 480P, 720P або 1080P. Prime резервує 12,2, 25,2 або 50,4 кредити за секунду. Rivya округлює загальний резерв угору лише один раз; розумна тривалість резервує 30 секунд. Коректне фактичне використання, що не перевищує резерв, завершує розрахунок і повертає різницю. Якщо фактичне використання відсутнє, некоректне або вище, резерв зберігається, а задача переходить на звірку без прихованого додаткового списання.

У режимі референсів Wan 3.0 передавайте щонайбільше 10 зображень, 5 відео й 5 аудіокліпів. Кожен відео- й аудіокліп може тривати від 1 до 15 секунд, а кожен тип має окремий сукупний ліміт 15 секунд. duration=-1 не можна використовувати з референс-відео; за наявності вхідного відео сума перевіреної тривалості вхідного відео й запитаної тривалості результату не повинна перевищувати 30 секунд.

Приклад запиту Video8 для синхронізації губ за відео й аудіо:

{
  "model": "volcengine-video-lip-sync",
  "prompt": "",
  "params": {
    "mode": "lite",
    "separate_vocal": "false",
    "open_scenedet": "false",
    "referenceMediaItems": [
      {
        "url": "https://.../source.mov",
        "kind": "video",
        "name": "source.mov",
        "mimeType": "video/quicktime",
        "durationSeconds": 12.4,
        "durationToken": "duration_token_from_files_api",
        "width": 1920,
        "height": 1080,
        "framesPerSecond": 30,
        "videoBitrateMbps": 8.5,
        "sizeBytes": 26214400,
        "videoMetadataToken": "video_metadata_token_from_files_api"
      },
      {
        "url": "https://.../dialogue.wav",
        "kind": "audio",
        "name": "dialogue.wav",
        "mimeType": "audio/wav",
        "durationSeconds": 12.4,
        "durationToken": "audio_duration_token_from_files_api"
      }
    ]
  }
}

Приклад curl

curl https://rivya.ai/api/v1/generations \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-preview-001" \
  -d '{
    "model": "z-image",
    "prompt": "A clean editorial product image on a soft studio background",
    "params": {
      "aspect_ratio": "1:1"
    }
  }'

Приклад JavaScript

const response = await fetch("https://rivya.ai/api/v1/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RIVYA_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "product-preview-001"
  },
  body: JSON.stringify({
    model: "z-image",
    prompt: "A clean editorial product image on a soft studio background",
    params: { aspect_ratio: "1:1" }
  })
});

const generation = await response.json();
console.log(generation.id, generation.status);

Приклад Python

import os
import requests

response = requests.post(
    "https://rivya.ai/api/v1/generations",
    headers={
        "Authorization": f"Bearer {os.environ['RIVYA_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "product-preview-001",
    },
    json={
        "model": "z-image",
        "prompt": "A clean editorial product image on a soft studio background",
        "params": {"aspect_ratio": "1:1"},
    },
    timeout=30,
)

generation = response.json()
print(generation["id"], generation["status"])

Відповідь

{
  "id": "task_public_id",
  "status": "queued",
  "model": "z-image",
  "reserved_credits": 1,
  "final_credits": 0,
  "created_at": "2026-05-10T00:00:00.000Z",
  "updated_at": "2026-05-10T00:00:00.000Z",
  "result": null,
  "error": null
}

Збережіть id і опитуйте статус генерації. Якщо ви налаштуєте API Webhooks, Rivya також може надіслати підписану подію generation.succeeded або generation.failed, коли задача досягне термінального стану.

Ідемпотентність

Використовуйте Idempotency-Key для повторних спроб. Якщо той самий ключ і те саме тіло запиту відтворюються повторно, Rivya може повернути збережену публічну відповідь замість створення дубліката задачі.

Якщо той самий ключ повторно використовується з іншими вхідними даними, API повертає idempotency_conflict.

Створення генерації