Indsend asynkrone Rivya API-genereringsjobs med model, prompt, params, Idempotency-Key og offentlige svarfelter.

Brug POST /api/v1/generations til at indsende et asynkront billed-, video- eller audiogenereringsjob.

For chatmodeller skal du bruge Chat API. POST /api/v1/generations opretter ikke chat-sessioner eller assistant-beskeder.

Endpoint

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

Påkrævede headers:

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

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

Felter:

model: påkrævet offentlig model-ID
prompt: prompttekst, påkrævet af mange modeller
params: modelspecifikt parameterobjekt
client_request_id: valgfrit trace-ID fra dit system

Læs Model API Reference for modelspecifikke params.

Referencefiler i params

For modeller, der accepterer uploadede referencemedier, skal du først kalde Files API. Send derefter uploadresultatet gennem modellens params; tilføj ikke et top-level files-felt til genereringsanmodningen.

Brug params.referenceMediaItems til nye integrationer:

{
  "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- eller videoinputs, der kræver varighedsverifikation, skal du inkludere den duration_token, der returneres af /api/v1/files, som durationToken på den relaterede referenceMediaItems-post.

Hvert Image5-referencebillede kræver width, height, size_bytes og image_dimensions_token fra det oprindelige modelbundne Files API-svar, sendt som width, height, sizeBytes og imageDimensionsToken. Et manglende, udløbet, uoverensstemmende eller klientopfundet token medfører afvisning før oprettelse af opgaven og reservation af kreditter. Layer Decomposition kræver desuden præcis ét billede inden for de dokumenterede geometriske grænser.

Grok Imagine Image 2.0 bruger de samme krav til signerede billedmetadata. Send ingen referenceelementer til tekst-til-billede; til standard billedredigering skal du sende 1–5 unikke signerede JPEG-, PNG- eller WebP-elementer. Tekst-til-billede accepterer 1:1, 2:3, 3:2, 16:9 eller 9:16; billedredigering accepterer desuden auto. Segment Map og Segment Edit kan ikke kaldes som tilstande via Public API.

Hver Video8-referencevideo kræver duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes og video_metadata_token fra det oprindelige modelbundne svar. Send dem som durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes og videoMetadataToken. Begge signerede tokens verificeres før oprettelse af opgaven og reservation af kreditter.

Wan 3.0 bruger tre gensidigt udelukkende værdier for seedance_scene. text accepterer ingen uploadede medier; frames kræver et første billede og tillader ét valgfrit sidste billede; reference accepterer en signeret samling af billeder, videoer og lyd, men lyd må ikke være det eneste medie. Alle reference-URL'er skal komme fra oprindelige modelbundne uploads i Files API. Genveje fra fil til video og fra link til video forbliver utilgængelige.

Indstil variant til standard eller prime, resolution til 480P, 720P eller 1080P og aspect_ratio til adaptive, 16:9, 4:3, 1:1, 3:4 eller 9:16. duration accepterer heltal fra 2 til 30 eller -1 for intelligent varighed; audio styrer modelskabt lyd, og seed accepterer 0 til 2147483647. Den trimmede prompt skal indeholde 1–20.000 tegn.

Wan 3.0 Standard reserverer 8, 16 eller 32 kreditter pr. ønsket resultatsekund ved 480P, 720P eller 1080P. Prime reserverer 12,2, 25,2 eller 50,4 kreditter pr. sekund. Rivya afrunder den samlede reservation op én gang; intelligent varighed reserverer 30 sekunder. Gyldigt faktisk forbrug, der ikke overstiger reservationen, afregnes, og forskellen refunderes. Hvis det faktiske forbrug mangler, er ugyldigt eller højere, beholdes reservationen og går til afstemning uden skjult ekstra debitering.

I Wan 3.0-referencetilstand kan du sende op til 10 billeder, 5 videoer og 5 lydklip. Video- og lydklip må hver være 1–15 sekunder, og hver type har en separat samlet grænse på 15 sekunder. duration=-1 kan ikke bruges med referencevideo; med videoinput må verificerede sekunder for inputvideoen plus ønskede outputsekunder ikke overstige 30.

Eksempel på en Video8-anmodning til synkronisering af læbebevægelser med video og lyd:

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

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-eksempel

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-eksempel

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

Svar

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

Gem id, og poll Genereringsstatus. Hvis du konfigurerer API Webhooks, kan Rivya også sende en signeret generation.succeeded- eller generation.failed-event, når opgaven når en terminal tilstand.

Idempotency

Brug Idempotency-Key til retries. Hvis samme key og samme request body afspilles igen, kan Rivya returnere det gemte offentlige svar i stedet for at oprette en dubletopgave.

Hvis samme key genbruges med et andet input, returnerer API'en idempotency_conflict.

Opret generation