Υποβάλετε ασύγχρονες εργασίες δημιουργίας στο Rivya API με model, prompt, params, Idempotency-Key και δημόσια πεδία απόκρισης.

Χρησιμοποιήστε POST /api/v1/generations για να υποβάλετε μια ασύγχρονη εργασία δημιουργίας εικόνας, βίντεο ή ήχου.

Για μοντέλα συνομιλίας, χρησιμοποιήστε το 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": "Μια καθαρή συντακτική εικόνα προϊόντος σε απαλό φόντο στούντιο",
  "params": {
    "aspect_ratio": "1:1"
  },
  "client_request_id": "order-123-preview"
}

Πεδία:

model: απαιτούμενο δημόσιο αναγνωριστικό μοντέλου
prompt: κείμενο προτροπής, απαιτείται από πολλά μοντέλα
params: αντικείμενο παραμέτρων ειδικό για το μοντέλο
client_request_id: προαιρετικό αναγνωριστικό ανίχνευσης από το σύστημά σας

Διαβάστε την Αναφορά API μοντέλων για τις παραμέτρους params που αφορούν συγκεκριμένο μοντέλο.

Αρχεία αναφοράς μέσα στο params

Για μοντέλα που δέχονται ανεβασμένα μέσα αναφοράς, καλέστε πρώτα το Files API. Έπειτα περάστε το αποτέλεσμα μεταφόρτωσης μέσω των params του μοντέλου· μην προσθέτετε πεδίο files ανώτατου επιπέδου στο αίτημα δημιουργίας.

Χρησιμοποιήστε params.referenceMediaItems για νέες ενσωματώσεις:

{
  "model": "nano-banana-2-lite",
  "prompt": "Αναδιαμόρφωσε αυτή τη φωτογραφία προϊόντος για μια καθαρή συντακτική σελίδα καταλόγου",
  "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. Ένα token που λείπει, έχει λήξει, δεν ταιριάζει ή επινοήθηκε από την εφαρμογή-πελάτη αποτυγχάνει πριν από τη δημιουργία εργασίας και τη δέσμευση μονάδων. Το Layer Decomposition απαιτεί επιπλέον ακριβώς μία εικόνα εντός των τεκμηριωμένων γεωμετρικών ορίων.

Το Grok Imagine Image 2.0 εφαρμόζει το ίδιο όριο ασφαλείας για τα υπογεγραμμένα metadata εικόνας. Για μετατροπή κειμένου σε εικόνα, μην στέλνετε στοιχεία αναφοράς. Για τυπική επεξεργασία εικόνας, στείλτε από μία έως πέντε μοναδικές, υπογεγραμμένες εικόνες 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. Και τα δύο υπογεγραμμένα token επαληθεύονται πριν από τη δημιουργία εργασίας και τη δέσμευση μονάδων.

Το 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 credits για κάθε ζητούμενο δευτερόλεπτο εξόδου σε 480P, 720P ή 1080P. Το Prime δεσμεύει 12,2, 25,2 ή 50,4 credits ανά δευτερόλεπτο. Το 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 και ελέγχετε περιοδικά την Κατάσταση δημιουργίας. Αν διαμορφώσετε Webhooks του API, το Rivya μπορεί επίσης να στείλει υπογεγραμμένο συμβάν generation.succeeded ή generation.failed όταν η εργασία φτάσει σε τελική κατάσταση.

Idempotency

Χρησιμοποιήστε Idempotency-Key για επαναλήψεις. Αν το ίδιο κλειδί και το ίδιο σώμα αιτήματος αναπαραχθούν, το Rivya μπορεί να επιστρέψει την αποθηκευμένη δημόσια απάντηση αντί να δημιουργήσει διπλή εργασία.

Αν το ίδιο κλειδί επαναχρησιμοποιηθεί με διαφορετική είσοδο, το API επιστρέφει idempotency_conflict.

Δημιουργία μέσω API