Create Generation

Use POST /api/v1/generations to submit an asynchronous image, video, or audio generation job.

For chat models, use Chat API. POST /api/v1/generations does not create chat sessions or assistant messages.

Endpoint

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

Required headers:

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

Recommended header:

Idempotency-Key: your-unique-request-key

Request Body

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

Fields:

• model: required public model ID

• prompt: prompt text, required by many models

• params: model-specific parameter object

• client_request_id: optional trace ID from your system

Read Model API Reference for model-specific params.

Reference Files In Params

For models that accept uploaded reference media, first call Files API. Then pass the upload result through model params; do not add a top-level files field to the generation request.

Use params.referenceMediaItems for new integrations:

{
  "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"
      }
    ]
  }
}

For audio or video inputs that require duration verification, include the duration_token returned by /api/v1/files as durationToken on the related referenceMediaItems entry.

Every Image5 reference image requires the original model-bound Files API response's width, height, size_bytes, and image_dimensions_token, sent as width, height, sizeBytes, and imageDimensionsToken. A missing, expired, mismatched, or client-invented token fails before task creation and credit reservation. Layer Decomposition additionally requires exactly one image within its documented geometry limits.

Grok Imagine Image 2.0 uses the same signed image-metadata boundary. Send no reference items for text-to-image, or one to five unique signed JPEG, PNG, or WebP items for standard image editing. Text-to-image accepts 1:1, 2:3, 3:2, 16:9, or 9:16; image editing additionally accepts auto. Segment Map and Segment Edit are not callable Public API modes.

Every Video8 reference video requires the original model-bound response's duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, and video_metadata_token. Send them as durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes, and videoMetadataToken. Both signed tokens are verified before task creation and credit reservation.

Wan 3.0 uses three mutually exclusive seedance_scene values. text accepts no uploaded media; frames requires one first image and allows one optional last image; reference accepts a signed bundle of images, videos, and audio, but audio cannot be the only media. All reference URLs must come from original model-bound Files API uploads. File-to-video and link-to-video shortcuts remain unavailable.

Set variant to standard or prime, resolution to 480P, 720P, or 1080P, and aspect_ratio to adaptive, 16:9, 4:3, 1:1, 3:4, or 9:16. duration accepts whole numbers from 2 through 30, or -1 for intelligent duration; audio controls model-created audio, and seed accepts 0 through 2147483647. The trimmed prompt must contain 1–20,000 characters.

Wan 3.0 Standard reserves 8, 16, or 32 credits per requested output second at 480P, 720P, or 1080P. Prime reserves 12.2, 25.2, or 50.4 credits per second. Rivya rounds the combined reservation up once; intelligent duration reserves 30 seconds. Valid actual usage at or below the reservation settles and refunds the difference. Missing, invalid, or higher actual usage keeps the reservation and enters reconciliation without a hidden extra debit.

In Wan 3.0 reference mode, send at most 10 images, 5 videos, and 5 audio clips. Video and audio clips each run from 1 through 15 seconds and each kind has a separate 15-second aggregate limit. duration=-1 cannot be used with reference video; with video input, verified input-video seconds plus requested output seconds must not exceed 30.

Example Video8 request for a video-and-audio lip-sync task:

{
  "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 Example

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 Example

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 Example

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"])

Response

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

Save the id and poll Generation Status. If you configure API Webhooks, Rivya can also send a signed generation.succeeded or generation.failed event when the task reaches a terminal state.

Idempotency

Use Idempotency-Key for retries. If the same key and same request body are replayed, Rivya can return the stored public response instead of creating a duplicate task.

If the same key is reused with different input, the API returns idempotency_conflict.

Related Pages

• Generation Status

• API Webhooks

• API Credits

• API Errors and Limits

• Model API Reference