ENDPOINT

POSThttps://platform-backend-test.topview.ai/api/v1/models/google/nano-banana-2.1/edit/predictions

Mode

Usage and billingDuration, media, and settlement rules

Authentication

Authenticate with your Platform API key in the Authorization header.

Authorization: Bearer YOUR_PLATFORM_KEYManage API keys

Your key needs models:generate and requests:read permissions. Only the following parameters are supported. Unsupported fields return 400 without a charge.

Submit a task

Submit model parameters directly; no estimate request is required. Save data.id to retrieve status, results and the final charge.

Use a unique Idempotency-Key per task. Retry an uncertain submission with the same key and request. Python / JavaScript save input and idempotency key before submission in REQUEST_STATE (default .topview-request.json); keep this file private. Restart with the same file to recover, or set TASK_ID for GET-only recovery. Use a new state path for a new task. Polling retries network errors, 429 and 5xx with bounded backoff and Retry-After; after the retry limit or 30 minutes, resume the saved task ID.

Upload reference media

Examples cover media fields supported by this capability. Use an existing public HTTPS URL directly, or upload a local file and use download_url. Asset IDs are optional. Model format and size limits still apply.

Media field Upload example language

curl --fail-with-body "https://platform-backend-test.topview.ai/api/v1/media/files" \
  -H "Authorization: Bearer $TOPVIEW_API_PLATFORM_KEY" \
  -F 'kind=image' -F 'file=@./reference.png'

# Optional: copy an existing HTTPS URL into your workspace
curl --fail-with-body "https://platform-backend-test.topview.ai/api/v1/media/imports" \
  -H "Authorization: Bearer $TOPVIEW_API_PLATFORM_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"kind":"image","url":"https://your-host/reference.png"}'
# Put the returned data.download_url into this model input:
# {"images":["DOWNLOAD_URL"]}
# Existing public HTTPS URLs can be used directly; uploading is optional.

Result Guide

Submit asynchronously and poll for results.

Save the task IDSave data.id after submission. HTTP 200 does not mean generation has completed.
Check progressCall GET with the original creating API key, requests:read and the corresponding mode permission. A new or rotated key cannot read the old key’s tasks. View Playground tasks in signed-in web history; authorized workspace members can also use web history after the original key expires or is revoked. Poll every 2–5 seconds and back off for long tasks or 429 / 5xx responses.
Read the resultKeep polling created / processing tasks. On completed, read data.outputs. On failed, read data.error and stop polling.
Handle pending paymentpayment_required means settlement needs more funds. amount_due_usd is the actual cost, additional_charge_usd is the amount above the original hold, and shortfall_usd is the eligible balance shortage. Top up the same workspace; settlement retries automatically without resubmitting. SynLink image tasks use the quoted maxChargeUsd as a spending ceiling; usage above it requires review and is not automatically collected. Other metered tasks may settle additional actual usage above the original hold from eligible balance.
Save files and verify chargesRead charged_usd and billing_state for settlement. Save results promptly because media URLs may expire. After a timeout, query the original task rather than creating a duplicate.

GEThttps://platform-backend-test.topview.ai/api/v1/predictions/REQUEST_ID

Replace REQUEST_ID with data.id. Poll data.status until completed or failed; successful results are in data.outputs.

createdprocessingpayment_requiredcompletedfailed

data.charged_usd is the actual task cost in USD, returned as an exact decimal string. data.billing_state: RESERVED holds funds, CAPTURED settles the charge, and RELEASED returns the hold.

Schema

Request and response schemas for the selected mode.

Each request generates one image asynchronously and returns a URL. Display prices are estimates; settlement uses actual consumption and releases unused funds. Read data.charged_usd for the actual USD charge.

If data.execution_state is REVIEW_REQUIRED, the upstream result or charge needs reconciliation and status may remain processing. Keep the task ID and contact support; do not resubmit with a new Idempotency-Key. Funds may remain RESERVED until reconciliation; a hold is not a completed charge.

Input schema

Common parameters match the Playground form. Use the API field path in request JSON; descriptions explain nested fields and media roles. — means no declared default, not null or zero.

Parameter / API path	Required	Type	Default	Options / limits	Description
`prompt`	Yes	`string`	—	max length 10000	Describe the desired content.
`images`	Yes	`string[]`	—	min items 1; max items 14	Input image URLs.
`aspect_ratio`	No	`string`	"1:1"	"1:1", "3:2", "2:3", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "1:4", "4:1", "1:8", "8:1"	Output aspect ratio.
`resolution`	No	`string`	"1k"	"1k", "2k", "4k"	Output resolution.

Advanced parameters and complete request structure

Parameter / API path	Required	Type	Default	Options / limits	Description
`output_format`	No	`string`	"png"	"png", "jpeg"	Output file format.
`enable_base64_output`	No	`boolean`	false	true, false	No additional description published.
`enable_sync_mode`	No	`boolean`	false	false	Only asynchronous submission is supported; true is not available.

Raw input JSON Schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "prompt",
    "images"
  ],
  "properties": {
    "enable_base64_output": {
      "type": "boolean",
      "default": false
    },
    "output_format": {
      "type": "string",
      "enum": [
        "png",
        "jpeg"
      ],
      "default": "png"
    },
    "prompt": {
      "type": "string",
      "maxLength": 10000
    },
    "images": {
      "type": "array",
      "minItems": 1,
      "maxItems": 14,
      "items": {
        "type": "string"
      }
    },
    "aspect_ratio": {
      "type": "string",
      "default": "1:1",
      "enum": [
        "1:1",
        "3:2",
        "2:3",
        "3:4",
        "4:3",
        "4:5",
        "5:4",
        "9:16",
        "16:9",
        "21:9",
        "1:4",
        "4:1",
        "1:8",
        "8:1"
      ]
    },
    "resolution": {
      "type": "string",
      "enum": [
        "1k",
        "2k",
        "4k"
      ],
      "default": "1k"
    },
    "enable_sync_mode": {
      "type": "boolean",
      "enum": [
        false
      ],
      "default": false,
      "description": "Only asynchronous submission is supported; true is not available."
    }
  }
}

Output schema

Task query response. Generation results are inside data. Nested field presence depends on the parent being returned.

Parameter / API path	Required	Type	Default	Options / limits	Description
`code`	Yes	`integer`	—	—	HTTP API envelope code. Inspect data.status for the task outcome.
`message`	Yes	`string`	—	—	API response message.
`data`	Yes	`object`	—	—	Prediction task details.
`data.id`	Yes	`string`	—	—	Platform task ID. Persist it before polling.
`data.created_at`	Yes	`string`	—	date-time	Task creation timestamp.
`data.code`	Yes	`integer`	—	—	0 for normal tasks; 402 when payment is required; 1403 for a failed task.
`data.execution_state`	Yes	`string`	—	—	Execution state; inspect status and billing_state before treating a task as settled.
`data.status`	Yes	`string`	—	"created", "processing", "payment_required", "completed", "failed"	Current task status.
`data.outputs`	Yes	`string[]`	—	—	Empty until settled successfully. HTTPS result URLs or image data; enable_base64_output returns raw Base64 without a data URI prefix.
`data.amount_due_usd`	No	`string`	—	—	Full actual cost in USD, present when status is payment_required.
`data.additional_charge_usd`	No	`string`	—	—	Actual cost minus the original reservation; present when payment is required.
`data.shortfall_usd`	No	`string`	—	—	Additional eligible balance needed at the latest settlement attempt. Top up this workspace; settlement retries automatically. No duplicate submission is needed.
`data.charged_usd`	Yes	`string`	—	—	Actual USD charge as an exact decimal string, not the reserved amount.
`data.billing_state`	Yes	`string`	—	"RESERVED", "CAPTURED", "RELEASED"	RESERVED is a temporary hold, not spending. CAPTURED is the final charge. RELEASED returns the full hold after failure; released funds are not recharge income.
`data.error`	Yes	`string`	—	—	Failure or payment-required description, otherwise an empty string.
`data.urls`	Yes	`object`	—	—	Task-related API URLs.
`data.urls.get`	Yes	`string`	—	uri	Authenticated polling URL. Use the original creating API key with requests:read and the corresponding mode permission.
`data.last_frame_url`	No	`string`	—	uri	Last-frame image URL when requested and returned, available only after settlement.

Raw output JSON Schema

{
  "type": "object",
  "required": [
    "code",
    "message",
    "data"
  ],
  "properties": {
    "code": {
      "type": "integer",
      "description": "HTTP API envelope code. Inspect data.status for the task outcome."
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "required": [
        "id",
        "created_at",
        "code",
        "execution_state",
        "status",
        "outputs",
        "charged_usd",
        "billing_state",
        "error",
        "urls"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Platform task ID. Persist it before polling."
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "code": {
          "type": "integer",
          "description": "0 for normal tasks; 402 when payment is required; 1403 for a failed task."
        },
        "execution_state": {
          "type": "string",
          "description": "Execution state; inspect status and billing_state before treating a task as settled."
        },
        "status": {
          "type": "string",
          "enum": [
            "created",
            "processing",
            "payment_required",
            "completed",
            "failed"
          ]
        },
        "outputs": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Empty until settled successfully. HTTPS result URLs or image data; enable_base64_output returns raw Base64 without a data URI prefix."
        },
        "amount_due_usd": {
          "type": "string",
          "description": "Full actual cost in USD, present when status is payment_required."
        },
        "additional_charge_usd": {
          "type": "string",
          "description": "Actual cost minus the original reservation; present when payment is required."
        },
        "shortfall_usd": {
          "type": "string",
          "description": "Additional eligible balance needed at the latest settlement attempt. Top up this workspace; settlement retries automatically. No duplicate submission is needed."
        },
        "charged_usd": {
          "type": "string",
          "description": "Actual USD charge as an exact decimal string, not the reserved amount.",
          "pattern": "^[0-9]+(\\.[0-9]+)?$",
          "example": "0.040000000000"
        },
        "billing_state": {
          "type": "string",
          "description": "RESERVED is a temporary hold, not spending. CAPTURED is the final charge. RELEASED returns the full hold after failure; released funds are not recharge income.",
          "enum": [
            "RESERVED",
            "CAPTURED",
            "RELEASED"
          ]
        },
        "error": {
          "type": "string",
          "description": "Failure or payment-required description, otherwise an empty string."
        },
        "urls": {
          "type": "object",
          "required": [
            "get"
          ],
          "properties": {
            "get": {
              "type": "string",
              "format": "uri",
              "description": "Authenticated polling URL. Use the original creating API key with requests:read and the corresponding mode permission."
            }
          }
        },
        "last_frame_url": {
          "type": "string",
          "format": "uri",
          "description": "Last-frame image URL when requested and returned, available only after settlement."
        }
      }
    }
  }
}

Errors

HTTP	What it means and what to do
`400`	Some parameters are invalid or unsupported. Check the schema and update your request.
`401`	Missing or invalid credentials. Check your API key.
`403`	Your API key doesn’t have the required permissions or model access. Check its settings.
`404`	This resource wasn’t found or isn’t accessible to your workspace.
`409`	Idempotency or version conflict. Check the original request.
`429`	Concurrency or rate limit reached. Wait and retry with backoff.
`5xx`	Temporary server error. Wait before retrying status checks. If you’re unsure whether a submission succeeded, retry with the same Idempotency-Key and request body.

HTTP success does not guarantee generation success. Inspect data.status, data.error and billing_state.

Nano Banana 2.1