API documentation

Submit media generation and transcription jobs, then poll for results. All endpoints are asynchronous: requests return a job ID immediately; processing happens in the background.

Base URL

https://api.ricsoft.com

Version prefix: /v1

Authentication

Create an API key in the user dashboard. Keys are shown only once at creation.

Send the key with either header:

Authorization: Bearer oa_your_api_key

X-API-Key: oa_your_api_key

Async job flow

Call an API endpoint with your parameters (and files when required).
Receive 202 Accepted with a job id.
Poll GET /v1/jobs/{id} until status is completed or failed.

Statuses: queued → processing → completed | failed

Submit response

{
  "id": "019f66eb-8bee-7066-8e36-8e2097b0c97b",
  "status": "queued",
  "api": "tts"
}

Errors & limits

Code	Meaning
401	Missing or invalid API key
403	Account disabled or API not assigned
422	Validation error (missing fields, bad file type)
429	Rate limit or monthly usage limit reached
404	Job not found (or not owned by this key’s user)

Rate limit: 60 requests / minute per API key
Usage is billed in seconds (audio or video) when a job completes, against your monthly per-API limit

GET

/v1/jobs/{id}

Retrieve job status and result (when completed).

Example

curl https://api.ricsoft.com/v1/jobs/JOB_ID \
  -H "Authorization: Bearer oa_your_api_key"

Completed response

{
  "id": "JOB_ID",
  "api": "tts",
  "status": "completed",
  "created_at": "2026-07-15T18:00:00+00:00",
  "started_at": "2026-07-15T18:00:01+00:00",
  "completed_at": "2026-07-15T18:00:12+00:00",
  "result": { },
  "result_files": { },
  "usage_units": 12
}

POST

/v1/tts

Generate audio from text using a selected voice. Usage: audio seconds.

Body (JSON)

Field	Type	Description
text	string	Required. Max 10,000 characters.
voice	string	Required. Voice identifier.

Example

curl -X POST https://api.ricsoft.com/v1/tts \
  -H "Authorization: Bearer oa_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from the API","voice":"alloy"}'

POST

/v1/voice-clone

Generate speech from text using a reference audio sample. Multipart form. Usage: audio seconds.

Body (multipart/form-data)

Field	Type	Description
text	string	Required. Max 10,000 characters.
audio	file	Required. Reference audio (mp3, wav, ogg, webm, m4a, flac). Max 25 MB.

Example

curl -X POST https://api.ricsoft.com/v1/voice-clone \
  -H "Authorization: Bearer oa_your_api_key" \
  -F "text=Speak like this" \
  -F "audio=@./reference.wav"

POST

/v1/transcribe

Convert audio to text. Multipart form. Usage: audio seconds (input duration).

Body (multipart/form-data)

Field	Type	Description
audio	file	Required. Audio file (mp3, wav, ogg, webm, m4a, flac). Max 50 MB.

Example

curl -X POST https://api.ricsoft.com/v1/transcribe \
  -H "Authorization: Bearer oa_your_api_key" \
  -F "audio=@./speech.mp3"

POST

/v1/video

Generate video from a prompt; optional audio and reference image. Multipart form. Usage: video seconds.

Body (multipart/form-data)

Field	Type	Description
prompt	string	Required. Max 5,000 characters.
audio	file	Optional. Formats: mp3, wav, ogg, webm, m4a, flac.
image	file	Optional. Formats: jpg, jpeg, png, webp.

Example

curl -X POST https://api.ricsoft.com/v1/video \
  -H "Authorization: Bearer oa_your_api_key" \
  -F "prompt=A calm lake at sunrise" \
  -F "image=@./reference.png"

POST

/v1/lipsync

Generate a lip-synced video from audio, an image, and a prompt. Multipart form. Usage: video seconds.

Body (multipart/form-data)

Field	Type	Description
prompt	string	Required. Max 5,000 characters.
audio	file	Required. Formats: mp3, wav, ogg, webm, m4a, flac.
image	file	Required. Formats: jpg, jpeg, png, webp.

Example

curl -X POST https://api.ricsoft.com/v1/lipsync \
  -H "Authorization: Bearer oa_your_api_key" \
  -F "prompt=Neutral talking head" \
  -F "audio=@./speech.wav" \
  -F "image=@./face.png"