{
"model_id": "google/nano-banana",
"prompt": "A cinematic beach sunset with palm trees",
"params": {
"aspect_ratio": "16:9",
"output_format": "jpeg"
}
}
{
"ok": true,
"code": 201,
"message": "Image generated",
"data": {
"image_id": "33333333-3333-4333-8333-333333333333",
"job_id": "33333333-3333-4333-8333-333333333333",
"file_id": null,
"output_url": null,
"preview_url": null,
"provider": "fal",
"model_id": "google/nano-banana",
"status": "processing",
"credits_used": 1
}
}
Studio AI
Generate Studio Image
Generate an AI Studio image with normalized params and optional model-specific raw passthrough.
POST
/
api
/
partner
/
v1
/
studio
/
images
/
generate
{
"model_id": "google/nano-banana",
"prompt": "A cinematic beach sunset with palm trees",
"params": {
"aspect_ratio": "16:9",
"output_format": "jpeg"
}
}
{
"ok": true,
"code": 201,
"message": "Image generated",
"data": {
"image_id": "33333333-3333-4333-8333-333333333333",
"job_id": "33333333-3333-4333-8333-333333333333",
"file_id": null,
"output_url": null,
"preview_url": null,
"provider": "fal",
"model_id": "google/nano-banana",
"status": "processing",
"credits_used": 1
}
}
Start one image generation job. The call is asynchronous: it returns
201 with an image_id,
status: "processing", and output_url: null. Poll
Get Studio Image with the image_id until output_url is set.
Credits are charged when the job starts (refunded if it fails), so keep the image_id. If you lose
it, find the result with List Studio Creations.
CLI: genviral studio-generate-image --model-id <id> --prompt <text> --wait starts the job and polls
until the image is ready.
Idempotency
Send a uniqueIdempotency-Key header for each image you intend to generate. Retrying the same key
with the same body replays the original result. When the header is omitted, Genviral derives a
stable key from the credential and request body for backward compatibility, so an identical
headerless request is treated as a retry rather than a new generation.
Body Parameters
Image model ID from Get Studio Models.
Optional input/reference image URLs. Genviral may mirror public reference URLs to its own CDN
before handing them to the upstream model so image-edit requests are less sensitive to third-party
hotlinking or fetch-policy issues.
Normalized image params. Supported keys:
aspect_ratio, resolution, output_format, size,
max_images, sequential_image_generation, scale_factor.Example
{
"model_id": "google/nano-banana",
"prompt": "A cinematic beach sunset with palm trees",
"params": {
"aspect_ratio": "16:9",
"output_format": "jpeg"
}
}
{
"ok": true,
"code": 201,
"message": "Image generated",
"data": {
"image_id": "33333333-3333-4333-8333-333333333333",
"job_id": "33333333-3333-4333-8333-333333333333",
"file_id": null,
"output_url": null,
"preview_url": null,
"provider": "fal",
"model_id": "google/nano-banana",
"status": "processing",
"credits_used": 1
}
}
Error Responses
400 invalid_json- request body is not valid JSON401- authentication failed (missing/invalid/revoked token)402 subscription_required- active Creator/Professional/Business plan required403 tier_not_allowed- Scheduler tier cannot use Partner API402 insufficient_credits- buy a credit pack athttps://www.genviral.io/billing?tab=credits, then retry422 invalid_payload(includes unsupportedmodel_id)422 invalid_input- upstream model rejected the provided prompt/image combination422 model_requires_image422 model_input_not_supported500 generation_failed
