Nano Banana 2.1 API integration

Choose generation or reference editing

fal documents google/nano-banana-2.1 for text-to-image and google/nano-banana-2.1/edit for image editing. Keep these separate in your application: an edit needs reference image URLs, while a new composition begins with a text brief.

Do not silently replace a failed request with a different model. Return a clear status and preserve the requested model identifier in your logs. This site’s private studio routes require its own signed-in account; a website API key is not a fal credential.

Submit from your server

Store the provider key in your server’s secret store. Your browser sends the prompt and allowed settings to your server; the server validates input and submits the provider request. Never put a real key in a public code example, client bundle or shared screenshot.

The sample below is a request template. FAL_KEY is a placeholder environment variable, not a credential supplied by this page. Add ownership checks, rate limits and a cost ceiling before allowing an end user to create a task.

# Run on your server with your own fal credential.
# Submits a billable provider task when executed with a valid key.
curl --request POST 'https://queue.fal.run/google/nano-banana-2.1' \
  --header "Authorization: Key $FAL_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"prompt":"A cobalt bottle on pale stone, soft side light, no text","aspect_ratio":"1:1","resolution":"1K","output_format":"png","num_images":1}'

# Save the returned request_id and use the documented status_url
# and response_url to follow the task. Do not repeat an ambiguous POST.

Treat generation as a queue task

Save the provider request identifier when a submission succeeds. Poll status with a reasonable interval and fetch the result only after completion. A signed webhook can reduce polling, but verify its authenticity before changing task or billing state.

Retry safe status reads after temporary network failures. Do not blindly retry an ambiguous submission: a duplicate can create two billed tasks. Associate the request identifier with your application’s task and credit transaction so support can investigate a problem.

Validate output settings and references

Use only settings supported by the chosen endpoint. Pin the desired output format and aspect ratio instead of forwarding arbitrary browser fields. If you accept image URLs, check their scheme and length, and control which storage locations your application can access.

Store the final image in storage you control when the workflow requires durable access. Return a task status instead of holding an HTTP request open for the entire generation. Test failure, timeout and cancellation paths before opening paid access.