{
"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": {
"file_id": "11111111-1111-1111-1111-111111111111",
"output_url": "https://cdn.example.com/partner-api/workspaces/ws_1/studio/images/image-123.jpeg",
"preview_url": "https://cdn.example.com/partner-api/workspaces/ws_1/studio/images/image-123.jpeg",
"provider": "fal",
"model_id": "google/nano-banana",
"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": {
"file_id": "11111111-1111-1111-1111-111111111111",
"output_url": "https://cdn.example.com/partner-api/workspaces/ws_1/studio/images/image-123.jpeg",
"preview_url": "https://cdn.example.com/partner-api/workspaces/ws_1/studio/images/image-123.jpeg",
"provider": "fal",
"model_id": "google/nano-banana",
"credits_used": 1
}
}
Generate one image synchronously and return its hosted output URL.
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
string
required
Image model ID from Get Studio Models.
string
required
Generation prompt.
string[]
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.
object
Normalized image params. Supported keys:
aspect_ratio, resolution, output_format, size,
max_images, sequential_image_generation, scale_factor.object
Optional model-specific passthrough params.
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": {
"file_id": "11111111-1111-1111-1111-111111111111",
"output_url": "https://cdn.example.com/partner-api/workspaces/ws_1/studio/images/image-123.jpeg",
"preview_url": "https://cdn.example.com/partner-api/workspaces/ws_1/studio/images/image-123.jpeg",
"provider": "fal",
"model_id": "google/nano-banana",
"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