Отправляйте асинхронные задачи генерации Rivya API с model, prompt, params, Idempotency-Key и публичными полями ответа.

Используйте POST /api/v1/generations, чтобы отправить асинхронную задачу генерации изображения, видео или аудио.

Для моделей чата используйте API чата. POST /api/v1/generations не создает чаты, сессии или сообщения ассистента.

Конечная точка

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: текст промпта, требуется многими моделями
params: объект параметров конкретной модели
client_request_id: необязательный ID трассировки из вашей системы

Модельные params описаны в справочнике Model API.

Справочные файлы в 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, привязанных к модели. Быстрые пути преобразования файла в видео и ссылки в видео остаются недоступны.

Установите 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. После удаления начальных и конечных пробелов промпт должен содержать от 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-вебхуки, Rivya также может отправить подписанное событие generation.succeeded или generation.failed, когда задача достигнет конечного состояния.

Идемпотентность

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

Если тот же ключ используется с другим вводом, API возвращает idempotency_conflict.

Создание генерации