Nano Banana 2.1 API 接入指南

选择生成或参考图编辑

fal 文档列出了文生图接口 google/nano-banana-2.1，以及图片编辑接口 google/nano-banana-2.1/edit。应用中应区分两者：编辑需要参考图片 URL，新构图从文字说明开始。

请求失败时不要悄悄替换为其他模型。返回明确状态，并在日志中保留请求模型标识。本站私有 studio 路由需要本站登录身份；网站 API key 不能替代 fal 密钥。

从服务端提交请求

将供应商密钥保存在服务端 secret 存储中。浏览器向你的服务端发送提示词和允许的设置；服务端校验输入，再提交供应商请求。不要把真实密钥放入公开示例、前端包或共享截图。

下方仅为请求模板。FAL_KEY 是环境变量占位符，本页没有提供密钥。允许终端用户创建任务前，应加入所有权检查、速率限制和费用上限。

# 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.

把生成当成队列任务

提交成功后保存供应商请求标识。按合理间隔查询状态，完成后再获取结果。签名 webhook 可以减少轮询，但更新任务或计费状态前必须验证来源。

临时网络失败后可以重试安全的状态查询。提交结果不明时不要盲目重发，重复请求可能创建两个计费任务。将供应商请求标识与应用任务、积分交易关联，方便排查。

校验输出设置与参考图片

只使用所选接口支持的设置。固定需要的文件格式与画幅，不要原样转发任意浏览器字段。接收图片 URL 时校验协议与长度，并控制应用能够访问的存储位置。

需要长期访问时，将最终图片保存到你控制的存储。返回任务状态，不要在整个生成期间一直占用 HTTP 请求。开放付费访问前测试失败、超时和取消路径。