Developer Quickstart

Authenticate, submit production and retrieve the result.

Every live Ruwana API product uses the same organization API key. Add an Idempotency-Key to production requests so safe retries resolve to the same logical request instead of creating duplicate work.

Open Platform View pricing

1. Create an organization API key

Sign in to Ruwana Platform, create or open your organization, then create the organization production API key. The full secret is shown only immediately after creation or regeneration.

export RUWANA_API_KEY="rw_live_..."

Keep the secret server-side. Do not embed a live production key in browser JavaScript or a public client application.

2. Authenticate every request

Use the organization key as a Bearer token.

Authorization: Bearer $RUWANA_API_KEY

3. Add an Idempotency-Key

Generate a stable unique value for each logical production request. Reusing the same key for the same request lets Platform return the existing request instead of replaying successful production and billing.

Idempotency-Key: order-1842-hero-image

Verify the key before starting production

GET /v1/account is a read-only authentication check. It lets a server verify the organization/key boundary before uploading media or creating billable production.

cURL

curl https://platform.ruwana.studio/v1/account \
  -H "Authorization: Bearer $RUWANA_API_KEY"

Node.js

const response = await fetch('https://platform.ruwana.studio/v1/account', {
  headers: { Authorization: 'Bearer ' + process.env.RUWANA_API_KEY }
});
console.log(await response.json());

Python

import os, requests

response = requests.get(
    'https://platform.ruwana.studio/v1/account',
    headers={'Authorization': 'Bearer ' + os.environ['RUWANA_API_KEY']}
)
print(response.json())

Image API examples

Creative can be text-only JSON or multipart when references are supplied. Product and Polish require one multipart image reference.

LAB Creative — text only

curl https://platform.ruwana.studio/v1/lab/creative \
  -H "Authorization: Bearer $RUWANA_API_KEY" \
  -H "Idempotency-Key: creative-001" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt":"Editorial still life with restrained luxury lighting",
    "resolution":"1K",
    "count":1
  }'

LAB Product — one reference

curl https://platform.ruwana.studio/v1/lab/product \
  -H "Authorization: Bearer $RUWANA_API_KEY" \
  -H "Idempotency-Key: product-001" \
  -F "references[]=@product.webp" \
  -F "prompt=Clean premium catalog composition" \
  -F "resolution=2K" \
  -F "count=1"

LAB Polish — one source image

curl https://platform.ruwana.studio/v1/lab/polish \
  -H "Authorization: Bearer $RUWANA_API_KEY" \
  -H "Idempotency-Key: polish-001" \
  -F "references[]=@source.jpg" \
  -F "resolution=2K" \
  -F "count=1"

Motion API example

Motion requires both media files. Duration is derived from motion_video; do not send a duration field.

curl https://platform.ruwana.studio/v1/motion/generate \
  -H "Authorization: Bearer $RUWANA_API_KEY" \
  -H "Idempotency-Key: motion-001" \
  -F "character_image=@character.png" \
  -F "motion_video=@movement.mp4" \
  -F "resolution=720p" \
  -F "character_orientation=video" \
  -F "keep_original_sound=true"

Accepted Motion duration is 3–30 seconds. The initial response contains a durable Platform request ID.

Avatar API examples

Send exactly one speech source: speech or an uploaded audio file.

Avatar with Ruwana TTS

curl https://platform.ruwana.studio/v1/avatar/generate \
  -H "Authorization: Bearer $RUWANA_API_KEY" \
  -H "Idempotency-Key: avatar-tts-001" \
  -F "avatar_image=@portrait.jpg" \
  -F "speech=Welcome to the new collection." \
  -F "resolution=720p" \
  -F "voice=Maya" \
  -F "voice_speed=100" \
  -F "emotion=Confident" \
  -F "prompt=Natural presenter performance with restrained gestures."

Avatar with uploaded audio

curl https://platform.ruwana.studio/v1/avatar/generate \
  -H "Authorization: Bearer $RUWANA_API_KEY" \
  -H "Idempotency-Key: avatar-audio-001" \
  -F "avatar_image=@portrait.jpg" \
  -F "audio=@voice.mp3" \
  -F "resolution=1080p" \
  -F "emotion=Luxury" \
  -F "prompt=Controlled premium delivery."

4. Read asynchronous request status

PRO, Video, Motion and Avatar use the same owner-bound request-status route. Poll the request returned by the original POST; do not submit the media again.

curl https://platform.ruwana.studio/v1/requests/$REQUEST_ID \
  -H "Authorization: Bearer $RUWANA_API_KEY"

While running

The response reports a non-terminal state such as audio preparation or production in progress. Continue reading the same request.

When succeeded

The response contains the retained result URL, billing details and media-expiry metadata. Save the media before the 7-day window ends.

5. Treat Platform media as delivery, not permanent storage

Successful generated media is retained for a fixed 7-day window from completion. Request, usage and billing history remain after the media URL expires, but your application should archive any result that must be kept permanently.

Continue into the full documentation

AuthenticationKey handling and Bearer authorization.Requests & statusDurable PRO, Video, Motion and Avatar lifecycle.ErrorsHTTP codes and safe retry behavior.Media retention7-day delivery and archival.

Production examplesCopy repeatable request recipes for real tasks.Production readinessLimits, retry rules, durable state and archival.Compare APIsChoose the right production system before integrating.

Ready to make the first request?

Open Platform, fund the organization wallet and create the production API key.

Open Platform API overview