สร้างงานผ่าน API

ใช้ POST /api/v1/generations เพื่อส่งงานสร้างภาพ วิดีโอ หรือเสียงแบบไม่ต้องรอให้เสร็จในคำขอเดียว

สำหรับโมเดลแชต ให้ใช้ Chat API ส่วน POST /api/v1/generations จะไม่สร้างเซสชันแชตหรือข้อความผู้ช่วย

ปลายทางของ API

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: รหัสโมเดลสาธารณะที่จำเป็น

• prompt: ข้อความ prompt ที่หลายโมเดลต้องใช้

• params: ออบเจ็กต์พารามิเตอร์เฉพาะโมเดล

• client_request_id: รหัสติดตามจากระบบของคุณ ไม่จำเป็นต้องระบุ

อ่าน เอกสารอ้างอิง API ของแต่ละโมเดล สำหรับ 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 ที่ได้จากการอัปโหลดเป็น durationToken ในรายการอ้างอิงที่เกี่ยวข้อง

รูปภาพอ้างอิงของ Image5 ทุกรูปต้องใช้ width, height, size_bytes และ image_dimensions_token จากคำตอบเดิมของ Files API ซึ่งผูกกับโมเดล โดยส่งเป็น width, height, sizeBytes และ imageDimensionsToken โทเคนที่หาย หมดอายุ ไม่ตรงกัน หรือผู้ใช้สร้างขึ้นเองจะถูกปฏิเสธก่อนสร้างงานและกันเครดิต ส่วน Layer Decomposition กำหนดให้มีรูปภาพเพียงหนึ่งรูปและต้องอยู่ภายในขีดจำกัดทางเรขาคณิตที่ระบุไว้

Grok Imagine Image 2.0 ใช้ขอบเขตความปลอดภัยเดียวกันสำหรับข้อมูลกำกับรูปภาพที่ลงลายเซ็น ในโหมด text-to-image อย่าส่งรายการอ้างอิง ส่วนการแก้ไขรูปภาพมาตรฐานให้ส่งรูป JPEG, PNG หรือ WebP ที่ไม่ซ้ำกันและลงลายเซ็นแล้ว 1–5 รูป โหมด text-to-image รองรับ 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 3 ค่าแบบเลือกได้เพียงค่าเดียว โหมด text ไม่รับสื่อที่อัปโหลด โหมด frames บังคับรูปแรก 1 รูปและเลือกรูปสุดท้ายได้อีก 1 รูป ส่วนโหมด 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"])

ผลตอบกลับของ API

{
  "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 เพื่อป้องกันคำขอซ้ำ

ใช้ Idempotency-Key เมื่อลองใหม่ หากเล่นซ้ำด้วยคีย์และเนื้อหาคำขอเดิม Rivya สามารถคืนคำตอบสาธารณะที่บันทึกไว้แทนการสร้างงานซ้ำ

หากใช้คีย์เดิมซ้ำกับอินพุตที่ต่างกัน API จะคืน idempotency_conflict

หน้าที่เกี่ยวข้อง

• สถานะงานสร้าง

• API Webhooks

• เครดิต API

• ข้อผิดพลาดและขีดจำกัด API

• เอกสารอ้างอิง API ของแต่ละโมเดล