Gửi tác vụ tạo nội dung bất đồng bộ qua Rivya API với mô hình, câu lệnh, tham số, Idempotency-Key và các trường phản hồi công khai.

Dùng POST /api/v1/generations để gửi một tác vụ tạo hình ảnh, video hoặc âm thanh bất đồng bộ.

Với mô hình chat, hãy dùng Chat API. POST /api/v1/generations không tạo phiên trò chuyện hoặc tin nhắn của trợ lý.

Điểm cuối

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

Các header bắt buộc:

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

Header được khuyến nghị:

Idempotency-Key: your-unique-request-key

Nội dung yêu cầu

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

Các trường:

model: ID mô hình công khai, bắt buộc
prompt: nội dung prompt, bắt buộc với nhiều mô hình
params: đối tượng tham số dành riêng cho mô hình
client_request_id: ID theo dõi tùy chọn từ hệ thống của bạn

Đọc Tài liệu tham chiếu API mô hình để biết params dành riêng cho từng mô hình.

Tệp tham chiếu trong params

Với các mô hình chấp nhận nội dung đa phương tiện tham chiếu đã tải lên, trước tiên hãy gọi Files API. Sau đó truyền kết quả tải lên qua params của mô hình; không thêm trường files ở cấp cao nhất vào yêu cầu tạo nội dung.

Dùng params.referenceMediaItems cho tích hợp mới:

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

Với đầu vào âm thanh hoặc video cần xác minh thời lượng, hãy thêm duration_token do /api/v1/files trả về dưới dạng durationToken trong mục referenceMediaItems liên quan.

Mỗi ảnh tham chiếu Image5 đều cần width, height, size_bytes và image_dimensions_token từ phản hồi Files API ban đầu được gắn với mô hình; hãy gửi chúng dưới dạng width, height, sizeBytes và imageDimensionsToken. Token bị thiếu, hết hạn, không khớp hoặc do phía máy khách tự tạo sẽ khiến yêu cầu thất bại trước khi tạo tác vụ và giữ trước credits. Layer Decomposition còn yêu cầu đúng một ảnh nằm trong các giới hạn hình học đã được ghi trong tài liệu.

Grok Imagine Image 2.0 áp dụng cùng quy tắc xác thực siêu dữ liệu ảnh có chữ ký. Không gửi mục tham chiếu nào khi tạo ảnh từ văn bản; với chỉnh sửa ảnh tiêu chuẩn, hãy gửi từ một đến năm mục JPEG, PNG hoặc WebP không trùng lặp và có chữ ký. Chế độ tạo ảnh từ văn bản chấp nhận 1:1, 2:3, 3:2, 16:9 hoặc 9:16; chỉnh sửa ảnh còn chấp nhận auto. Segment Map và Segment Edit không phải là các chế độ có thể gọi qua Public API.

Mỗi video tham chiếu Video8 đều cần duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes và video_metadata_token từ phản hồi ban đầu được gắn với mô hình. Hãy gửi chúng dưới dạng durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes và videoMetadataToken. Cả hai token có chữ ký đều được xác minh trước khi tạo tác vụ và giữ trước credits.

Wan 3.0 sử dụng ba giá trị seedance_scene loại trừ lẫn nhau. text không nhận nội dung tải lên; frames yêu cầu một ảnh đầu tiên và cho phép thêm một ảnh cuối tùy chọn; reference nhận một bộ ảnh, video và âm thanh có chữ ký, nhưng âm thanh không thể là nội dung duy nhất. Mọi URL tham chiếu phải đến từ lượt tải lên Files API ban đầu được gắn với mô hình. Các lối tắt file-to-video và link-to-video vẫn chưa khả dụng.

Đặt variant thành standard hoặc prime, resolution thành 480P, 720P hoặc 1080P, và aspect_ratio thành adaptive, 16:9, 4:3, 1:1, 3:4 hoặc 9:16. duration nhận số nguyên từ 2 đến 30, hoặc -1 cho thời lượng thông minh; audio điều khiển âm thanh do mô hình tạo, còn seed nhận giá trị từ 0 đến 2147483647. Prompt sau khi loại bỏ khoảng trắng thừa phải có từ 1–20.000 ký tự.

Wan 3.0 Standard giữ trước 8, 16 hoặc 32 credits cho mỗi giây đầu ra được yêu cầu ở 480P, 720P hoặc 1080P. Prime giữ trước 12,2, 25,2 hoặc 50,4 credits mỗi giây. Rivya chỉ làm tròn lên một lần cho tổng số credits giữ trước; thời lượng thông minh giữ trước 30 giây. Mức sử dụng thực tế hợp lệ và không vượt quá số giữ trước sẽ được quyết toán, đồng thời hoàn lại phần chênh lệch. Nếu mức sử dụng thực tế bị thiếu, không hợp lệ hoặc cao hơn, hệ thống giữ nguyên số credits đã giữ trước và chuyển sang đối soát mà không có khoản trừ thêm ẩn.

Trong chế độ tham chiếu Wan 3.0, hãy gửi tối đa 10 ảnh, 5 video và 5 đoạn âm thanh. Mỗi đoạn video hoặc âm thanh dài từ 1 đến 15 giây, và mỗi loại có giới hạn tổng thời lượng riêng là 15 giây. Không thể dùng duration=-1 cùng video tham chiếu; khi có video đầu vào, tổng số giây video đầu vào đã xác minh và số giây đầu ra được yêu cầu không được vượt quá 30.

Ví dụ yêu cầu Video8 cho tác vụ đồng bộ khẩu hình sử dụng video và âm thanh:

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

Ví dụ 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"
    }
  }'

Ví dụ 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);

Ví dụ 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"])

Phản hồi

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

Hãy lưu id và thăm dò Trạng thái tạo nội dung. Nếu bạn cấu hình API Webhooks, Rivya cũng có thể gửi sự kiện generation.succeeded hoặc generation.failed có chữ ký khi tác vụ đạt trạng thái cuối.

Idempotency

Dùng Idempotency-Key khi thử lại. Nếu cùng một khóa và cùng nội dung yêu cầu được gửi lại, Rivya có thể trả về phản hồi công khai đã lưu thay vì tạo tác vụ trùng lặp.

Nếu cùng một khóa được dùng lại với đầu vào khác, API trả về idempotency_conflict.

Tạo nội dung