엔드포인트

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: 필수 공개 모델 ID
prompt: 프롬프트 텍스트이며 많은 모델에서 필수입니다.
params: 모델별 매개변수 객체
client_request_id: 사용자의 시스템에서 전달하는 선택적 추적 ID

모델별 params는 모델 API 참고 문서를 확인하세요.

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

재생 시간 검증이 필요한 오디오 또는 비디오 입력은 /api/v1/files가 반환한 duration_token을 해당 referenceMediaItems 항목의 durationToken으로 넣으세요.

Image5 참조 이미지는 모두 원래의 모델 지정 Files API 응답에 포함된 width, height, size_bytes, image_dimensions_token을 각각 width, height, sizeBytes, imageDimensionsToken으로 전달해야 합니다. 토큰이 없거나 만료되었거나 메타데이터와 일치하지 않거나 클라이언트가 임의로 만든 경우, 작업 생성 및 크레딧 예약 전에 요청이 실패합니다. Layer Decomposition은 문서화된 기하 범위 안의 이미지 정확히 1개를 추가로 요구합니다.

Grok Imagine Image 2.0은 동일한 서명 이미지 메타데이터 검증 요건을 따릅니다. 텍스트-이미지 생성에는 참조 항목을 보내지 마세요. 표준 이미지 편집에는 중복되지 않는 서명된 JPEG, PNG 또는 WebP 이미지 참조를 1–5개 보내세요. 텍스트-이미지 생성은 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 값을 사용합니다. text는 업로드 미디어를 허용하지 않습니다. frames는 첫 이미지를 필수로 요구하고 마지막 이미지는 선택적으로 허용합니다. reference는 서명된 이미지, 비디오 및 오디오 묶음을 허용하지만 오디오만 단독으로 사용할 수는 없습니다. 모든 참조 URL은 원래의 모델 지정 Files API 업로드에서 가져와야 합니다. 파일 기반 비디오 생성과 링크 기반 비디오 생성의 단축 경로는 계속 사용할 수 없습니다.

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을 허용합니다. 앞뒤 공백을 제거한 프롬프트는 1–20,000자여야 합니다.

Wan 3.0 Standard는 480P, 720P 또는 1080P에서 요청한 출력 1초당 각각 8, 16 또는 32크레딧을 예약합니다. Prime은 1초당 각각 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"])

응답

{
  "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 Webhook을 구성하면 작업이 최종 상태에 도달할 때 Rivya가 서명된 generation.succeeded 또는 generation.failed 이벤트도 보낼 수 있습니다.

멱등성

재시도에는 Idempotency-Key를 사용하세요. 동일한 키와 동일한 요청 본문을 다시 보내면 Rivya는 중복 작업을 만들지 않고 저장된 공개 응답을 반환할 수 있습니다.

동일한 키를 서로 다른 입력에 재사용하면 API는 idempotency_conflict를 반환합니다.

생성 작업 만들기