FAQ

Timeout and Performance Issues

How long should the timeout be set?

Considering image upload time, API processing time, and image download time, avoid setting the time too short to complete. The time setting should err on the side of being longer rather than shorter.

Since transmission uses base64 encoding, the data volume is large. It is recommended to change the client's bandwidth to metered high-speed bandwidth to avoid congestion.

Recommended Timeout Settings

Set reasonable timeout values based on different resolutions:

Resolution	Recommended Timeout	Description
1K	360 seconds (6 minutes)	Quick preview
2K	600 seconds (10 minutes)	Recommended for daily use
4K	1200 seconds (20 minutes)	Ultra HD quality

Code Example

TIMEOUT = {
    "1K": 360,   # 6 minutes - Quick preview
    "2K": 600,   # 10 minutes - Recommended
    "4K": 1200,  # 20 minutes - Ultra HD
}

# Usage
response = requests.post(
    API_URL,
    headers=headers,
    json=payload,
    timeout=TIMEOUT[resolution]
)

Why is transmission speed slow?

Reasons:

Image data uses base64 encoding, approximately 33% larger than original file
4K image base64 data may exceed 10MB
Network bandwidth limitations

Solutions:

Use metered high-speed bandwidth
Choose lower resolution (e.g., 2K instead of 4K)
Use in good network conditions
Consider using CDN or nearby API nodes

Content Restriction Issues

What content can Nano Banana Pro API not process?

When encountering content that cannot be processed, the API typically returns:

{
  "text": "I'm just a language model and can't help with that."
}

Common Rejected Content Types

Content Type	Description	Return Result
Watermark Removal	`remove watermark`	Refuses processing, no image data returned
Face Swap	`faceswap`	Refuses processing, no image data returned
NSFW Content	Inappropriate content	Refuses processing, or returns empty
Violence/Gore	Violent content	Refuses processing
Copyrighted Content	Copyright-infringing content	Refuses processing

Example

# ❌ Requests that will be rejected
bad_prompts = [
    "remove watermark from this image",
    "faceswap to another person",
    # ... other violating content
]

# ✅ Compliant requests
good_prompts = [
    "enhance the image quality",
    "add artistic effects",
    "change the background to a sunset",
]

How to determine if a request is rejected?

Check if the response contains a rejection message:

def check_rejection(response_data):
    """Check if API rejected the request"""
    try:
        candidates = response_data.get("candidates", [])
        if not candidates:
            return True, "No candidate results returned"
        
        parts = candidates[0].get("content", {}).get("parts", [])
        for part in parts:
            # Check for text rejection message
            if "text" in part:
                text = part["text"]
                if "can't help with that" in text.lower():
                    return True, "API refused to process this content"
            
            # Check for image data
            if "inlineData" in part or "inline_data" in part:
                return False, "Request successful"
        
        return True, "No image data found in response"
    except Exception as e:
        return True, f"Parsing error: {str(e)}"

# Usage example
is_rejected, message = check_rejection(response.json())
if is_rejected:
    print(f"⚠️ {message}")

Knowledge Base Limitations

Knowledge Base Update Time Limitation

Nano Banana Pro's knowledge base is updated as of January 2025 (official documentation).

Impact Example

If you ask to modify an item in an image to a new product:

# ❌ May fail: Product released after knowledge base cutoff date
PROMPT = "Replace the phone in the image with iPhone 17"

# ✅ Better approach: Use generic description
PROMPT = "Replace the phone in the image with latest smartphone model, black, large screen"

Solutions

Avoid time-sensitive descriptions:
- ❌ "2026 latest model car"
- ✅ "Modern style luxury sedan"
Use detailed physical descriptions:
- ❌ "iPhone 17"
- ✅ "Black large-screen smartphone, rounded corners, triple camera"
Provide reference image (image-to-image): Upload a reference image as style guide

Response Format Issues

How to handle response data format changes?

Field names in API responses may use camelCase or snake_case:

def extract_image_data(response_data):
    """Extract image data compatible with different naming formats"""
    try:
        parts = response_data["candidates"][0]["content"]["parts"]
        
        for part in parts:
            # Try camelCase (inlineData)
            if "inlineData" in part:
                return part["inlineData"]["data"]
            
            # Try snake_case (inline_data)
            if "inline_data" in part:
                return part["inline_data"]["data"]
        
        return None
    except (KeyError, IndexError):
        return None

# Usage example
image_data = extract_image_data(response.json())
if image_data:
    print("✅ Successfully extracted image data")
else:
    print("❌ No image data found")

Response contains only text, no image?

Possible reasons:

Response mode not specified:

# ❌ Wrong: Didn't specify return image
payload = {
    "contents": [{"parts": [{"text": "generate an image"}]}]
}

# ✅ Correct: Explicitly specify return image
payload = {
    "contents": [{"parts": [{"text": "generate an image"}]}],
    "generationConfig": {
        "responseModalities": ["IMAGE"]  # Key configuration
    }
}

Content rejected: Check if content restrictions were triggered
API error: Check HTTP status code and error message

Image Quality Issues

What to do if generated image quality is poor?

1. Improve Prompt Quality

# ❌ Vague prompt
prompt = "a cat"

# ✅ Detailed prompt
prompt = """
An orange short-haired cat, sitting on a windowsill,
sunlight shining through the window on it,
oil painting style, rich in detail, high definition,
soft lighting, warm tones
"""

2. Use Higher Resolution

# Upgrade from 1K to 2K or 4K
"generationConfig": {
    "imageConfig": {
        "image_size": "2K"  # or "4K"
    }
}

3. Add Quality Keywords

Include in prompt:

"high quality"
"detailed"
"professional photography"
"8K resolution"
"sharp and clear"

What to do if unwanted elements appear in image?

Use negative prompts (if supported) or explicitly state in prompt:

prompt = """
A cat sitting in a garden,
realistic style, high definition,
no other animals,
no people,
keep background simple
"""

Error Handling

How to gracefully handle various errors?

Complete error handling example:

import requests
import time

def safe_api_call(payload, max_retries=3):
    """Safe API call with retry mechanism"""
    
    for attempt in range(max_retries):
        try:
            response = requests.post(
                API_URL,
                headers=headers,
                json=payload,
                timeout=600
            )
            
            # HTTP error
            if response.status_code != 200:
                if response.status_code == 429:  # Rate limit
                    wait_time = (attempt + 1) * 10
                    print(f"⚠️ Rate limited, waiting {wait_time} seconds...")
                    time.sleep(wait_time)
                    continue
                else:
                    return None, f"HTTP {response.status_code}: {response.text}"
            
            # Parse response
            data = response.json()
            
            # Check if rejected
            is_rejected, message = check_rejection(data)
            if is_rejected:
                return None, f"Request rejected: {message}"
            
            # Extract image data
            image_data = extract_image_data(data)
            if image_data:
                return image_data, "Success"
            else:
                return None, "No image data found in response"
        
        except requests.exceptions.Timeout:
            print(f"⚠️ Request timeout (attempt {attempt + 1}/{max_retries})")
            if attempt < max_retries - 1:
                time.sleep(5)
                continue
            return None, "Request timeout"
        
        except requests.exceptions.ConnectionError:
            print(f"⚠️ Network connection error (attempt {attempt + 1}/{max_retries})")
            if attempt < max_retries - 1:
                time.sleep(5)
                continue
            return None, "Network connection error"
        
        except Exception as e:
            return None, f"Unknown error: {str(e)}"
    
    return None, "Retry attempts exhausted"

# Usage example
image_data, message = safe_api_call(payload)
if image_data:
    print(f"✅ {message}")
    # Save image...
else:
    print(f"❌ Failed: {message}")