Create generation tasks with the API
Submit image, video, and audio tasks with the Rivya API. See request fields, reference inputs, credit reservations, and idempotency rules.
Last reviewed on November 11, 2026
Use POST /api/v1/generations to create a generation task with an image, video, or audio model. Save the task ID to track its progress. Lyrics models return text rather than an audio file.
For chat models, use Chat API. POST /api/v1/generations does not create chat sessions or assistant messages.
A model can be listed in the catalog without being callable. Check its api_status, supported inputs, and parameters in Model API Reference before submitting work.
Suno Speech: scenes and supplied scripts
Suno Speech: prompt is the scene in Simple mode (params.customMode="false") or the script in Advanced mode ("true"). Advanced-only settings are tone, variety, vocalGender and backgroundMusic. Omit them in Simple mode; do not send a second script or prompt inside params.
Prompt units and complete layer results
Read prompt_length_unit together with max_prompt_length from GET /api/v1/models. utf8_bytes counts the original text bytes, including spaces and line breaks; utf16_code_units counts JavaScript UTF-16 units. A null limit does not mean unlimited or optional text. Gemini TTS uses the byte unit.
A completed layer-decomposition result can include result.layers alongside the complete result.urls list. Keep each layer’s z_index, URL, size, name, description and bounding box when provided; index zero is the base image. The TypeScript SDK exposes these fields. Upload references for the selected model and pass its original signed metadata; declared dimensions or duration alone do not replace verification.
Endpoint
You need a Bearer API key with generations:create or *. Requests use the account behind that key and the same credit balance as Studio. Browser sign-in alone does not authenticate an API request. See API key authentication.
Endpoint notation:
POST https://rivya.ai/api/v1/generationsSend these HTTP headers:
Authorization: Bearer rvya_sk_...
Content-Type: application/jsonRecommended for retries:
Idempotency-Key: your-unique-request-keyInclude Idempotency-Key on the first attempt and reuse it, with the unchanged body, when retrying. Use a new key for a new request. The Idempotency section explains the replay and conflict cases.
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"
}Request fields:
model: required public model ID, such asz-image. Use the ID rather than the display name or provider model name.prompt: optional request field. Whether it is required, and its length limit, depend on the model and mode.params: optional object containing the selected model's parameters and reference inputs. Accepted keys and values vary by model.client_request_id: optional trace ID from your system, up to 128 characters. It does not replaceIdempotency-Key.
Read Model API Reference for the selected model's params, input rules, and current availability.
Reference Files In Params
For models that accept uploaded references, first use Files API with the same model ID. Put the returned reference data in params; there is no top-level files field in the generation request.
Use params.referenceMediaItems for new integrations:
{
"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"
}
]
}
}The URLs, tokens, and measurements in these reference examples are illustrative. Replace each entry with the original values from your own Files API response. Editing a signed value can make the reference invalid.
For audio or video inputs that require duration verification, pass the Files API response's duration_token as durationToken on the matching referenceMediaItems entry. Also include its mime_type as mimeType and size_bytes as sizeBytes when required by the model.
For seedream-5-pro, seedream-5-pro-layer-decomposition, nano-banana-2-lite, qwen-image-3, and qwen-image-3-pro, map the original upload response's mime_type, width, height, size_bytes, and image_dimensions_token to mimeType, width, height, sizeBytes, and imageDimensionsToken.
These tokens must match the account, model, URL, and uploaded metadata. Missing, expired, mismatched, or invented tokens are rejected before task creation and credit reservation. Layer Decomposition also requires exactly one image within its model's geometry limits.
Grok Imagine Image 2.0 uses signed image metadata too. Text-to-image takes no references; standard image editing takes one to five unique signed JPEG, PNG, or WebP images. Text-to-image accepts 1:1, 2:3, 3:2, 16:9, or 9:16; editing also accepts auto. Segment Map and Segment Edit are not callable Public API modes.
For models that require signed video metadata, copy the original upload response's duration_seconds, duration_token, video_width, video_height, frames_per_second, video_bitrate_mbps, video_file_size_bytes, and video_metadata_token as durationSeconds, durationToken, width, height, framesPerSecond, videoBitrateMbps, sizeBytes, and videoMetadataToken. Both signed tokens are checked before task creation and credit reservation.
Wan 3.0 inputs and reservation
Wan 3.0 uses three mutually exclusive seedance_scene values. text takes no uploaded media. frames needs a first image and allows an optional last image. reference accepts signed images, videos, and audio, but audio cannot be the only media. Use original model-bound Files API uploads for every reference URL. File-to-video and link-to-video shortcuts are unavailable.
Set variant to standard or prime, resolution to 480P, 720P, or 1080P, and aspect_ratio to adaptive, 16:9, 4:3, 1:1, 3:4, or 9:16. duration takes whole numbers from 2 through 30, or -1 for intelligent duration. audio controls model-created audio, and seed accepts 0 through 2147483647.
Text mode requires a trimmed prompt of 1–20,000 characters. Frames and reference modes allow a blank prompt; any prompt you provide must stay within 20,000 characters.
Wan 3.0's reservation uses the selected variant and resolution rate multiplied by the total of requested output seconds and verified reference-video seconds. Rivya rounds the combined amount up once. Intelligent duration reserves 30 output seconds. See the Wan 3.0 API reference for current Standard and Prime rates at each resolution.
Valid final usage at or below the reservation is settled, with any unused credits returned. Missing, invalid, or higher usage leaves the reservation recorded as RECONCILIATION_REQUIRED; this state does not automatically charge the excess.
In Wan 3.0 reference mode, use at most 10 images, 5 videos, and 5 audio clips. Each video or audio clip must be 1–15 seconds, and video and audio each have a separate 15-second total limit. You cannot use duration=-1 with a reference video. With video input, verified input-video seconds plus requested output seconds must not exceed 30.
Video and audio lip-sync example
This volcengine-video-lip-sync example uses one video and one audio reference. The sample measurements fit the input limits, but the placeholder tokens are not valid signatures. Replace the URLs, tokens, MIME types, and measurements together with your own upload response values.
{
"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": 13175000,
"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",
"sizeBytes": 1190444
}
]
}
}curl Example
Replace rvya_sk_... with your server-side API key. The request below submits the same square Z-Image example shown above; it creates a task when accepted.
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 Example
Run this as a server-side JavaScript module with fetch available and RIVYA_API_KEY set. Check the HTTP result before treating the response as a task.
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();
if (!response.ok) {
throw new Error(JSON.stringify(generation.error));
}
console.log(generation.id, generation.status);Python Example
This example needs the requests package and RIVYA_API_KEY in the server environment. Its 30-second timeout limits the HTTP wait; it does not set the generation duration or prove a timed-out task failed.
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()
if not response.ok:
raise RuntimeError(generation.get("error"))
print(generation["id"], generation["status"])The examples reuse one idempotency key to show retries of the same request. Use a different key for a separate generation, and keep API keys out of browser code and public repositories.
Response
The amounts and timestamps below are example values, not a live result or a price quote. This illustrates a Z-Image task after submission to the provider: its status is processing, final_credits initially equals the reservation, and RESERVED means usage has not been settled.
{
"id": "task_public_id",
"status": "processing",
"model": "z-image",
"reserved_credits": 1,
"final_credits": 1,
"settlement_status": "RESERVED",
"created_at": "2026-05-10T00:00:00.000Z",
"updated_at": "2026-05-10T00:00:00.000Z",
"result": null,
"error": null
}Read task status and settlement_status separately. A task can succeed while its credits still need settlement. See API Credits for reservations, final usage, and credit returns.
Save the id and follow Generation Status to read the existing task. A missing or unclear response does not confirm that no task was created. If you already have an ID, check that task before submitting new work.
With API Webhooks enabled and an active endpoint configured, Rivya can send signed generation.succeeded or generation.failed events. A success event is queued after credit settlement is SETTLED. A failure event alone does not confirm a credit return.
Idempotency
Send Idempotency-Key on the original attempt, then reuse it with the unchanged body for retries. Its record belongs to that Rivya account and API key. Keep client_request_id unchanged too, if you supplied one.
If a response has already been stored for that key and body, Rivya returns the recorded public response without creating another task. The stored response can also be an error. Use Generation Status for the task's current state; a replay is not a fresh status check.
Reusing the key with a different body returns idempotency_conflict (409). An existing record without a stored response also returns this conflict, even when the body is unchanged.
If the request outcome is unclear, keep its key and body. Check the original task if you have its ID. Keep any requestId from an error response while resolving the request; changing the key can create another task and reserve credits again.
Keep idempotency keys within 128 characters; longer values are truncated. This limit applies to the header, separately from the optional client_request_id field.
Common questions
Does client_request_id prevent duplicates?
No. It is a trace field. Use Idempotency-Key for request replay, and keep the same body when retrying.
Can I reuse the same idempotency key with a different API key?
Idempotency records belong to one API key and account. Using another API key does not replay the first key's record, even when both keys use the same account balance.
Does a failed request mean the credits were returned?
Not by itself. Check the existing task and its settlement fields when you have its ID. insufficient_credits (402) means the account could not cover the initial reservation; other credit-processing errors can return internal_error (500). See API Errors and Limits for the response format and retry conditions.
