Quickstart: Make Your First Generation API Request

This guide walks you through generating an image with Nano Banana using APIXO’s async task flow.

Prerequisites

An APIXO account (sign up free)
For the direct REST examples below, your API key (get one here). The remote MCP connection uses browser OAuth instead.

Let your AI coding tool integrate APIXO for you

Connect Cursor, Claude Code, Codex, or another client with remote MCP and OAuth support to APIXO MCP at https://mcp.apixo.ai/mcp, using the name apixo-mcp. Sign in through apixo.ai browser OAuth. No local MCP installation, Node.js, or API key shared with the AI client is required. Once connected, try a prompt like:

Use the apixo-mcp connection. Add a server route to my Next.js app that calls
nano-banana to generate a 16:9 image from a prompt field in the request body,
and polls until the result URL is ready. Read its schema first. Use my existing
fetch helpers and TypeScript types. Keep application credentials server-side.
Do not submit a generation while writing the code.

The agent can use the free, read-only list_models and get_model_schema tools to discover a model’s parameters, then write the generateTask + statusTask REST flow into your codebase. get_profile confirms which account is connected, for free. MCP generation tools such as generate_task are billable; get_generation checks a generation’s status and result. The MCP catalog covers generation task models and excludes Chat/LLM gateways. For those models, use the Chat API or compatible SDKs, changing the base URL and configuring an APIXO API key in your application.

Connect APIXO MCP

Remote setup for Codex, Claude Code, Cursor, and other clients, with browser sign-in and free verification tools.

Prefer to wire up the API yourself? Continue with the steps below.

Step 1: Submit a Generation Task

cURL
JavaScript
Python

curl -X POST https://api.apixo.ai/api/v1/generateTask/nano-banana \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "async",
    "input": {
      "mode": "text-to-image",
      "prompt": "A serene Japanese garden with cherry blossoms, golden hour lighting, photorealistic",
      "aspect_ratio": "16:9"
    }
  }'

const API_KEY = 'YOUR_API_KEY';
const MODEL = 'nano-banana';

// Step 1: Submit task
const submitResponse = await fetch(
  `https://api.apixo.ai/api/v1/generateTask/${MODEL}`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      request_type: 'async',
      input: {
        mode: 'text-to-image',
        prompt: 'A serene Japanese garden with cherry blossoms, golden hour lighting, photorealistic',
        aspect_ratio: '16:9',
      },
    }),
  }
);

const { data } = await submitResponse.json();
console.log('Task ID:', data.taskId);

import requests
import time

API_KEY = 'YOUR_API_KEY'
MODEL = 'nano-banana'

# Step 1: Submit task
response = requests.post(
    f'https://api.apixo.ai/api/v1/generateTask/{MODEL}',
    headers={
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json',
    },
    json={
        'request_type': 'async',
        'input': {
            'mode': 'text-to-image',
            'prompt': 'A serene Japanese garden with cherry blossoms, golden hour lighting, photorealistic',
            'aspect_ratio': '16:9',
        },
    }
)

task_id = response.json()['data']['taskId']
print(f'Task ID: {task_id}')

Response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_abc123xyz"
  }
}

Step 2: Poll for Results

Wait a few seconds, then check the task status:

cURL
JavaScript
Python

curl "https://api.apixo.ai/api/v1/statusTask/nano-banana?taskId=task_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

// Step 2: Poll for results
const pollForResult = async (taskId) => {
  while (true) {
    await new Promise(resolve => setTimeout(resolve, 3000)); // Wait 3s
    
    const statusResponse = await fetch(
      `https://api.apixo.ai/api/v1/statusTask/${MODEL}?taskId=${taskId}`,
      {
        headers: { 'Authorization': `Bearer ${API_KEY}` },
      }
    );
    
    const result = await statusResponse.json();
    
    if (result.data.state === 'success') {
      const urls = JSON.parse(result.data.resultJson).resultUrls;
      console.log('Generated images:', urls);
      return urls;
    }
    
    if (result.data.state === 'failed') {
      throw new Error(result.data.failMsg);
    }
    
    console.log('Status:', result.data.state);
  }
};

const imageUrls = await pollForResult(data.taskId);

# Step 2: Poll for results
def poll_for_result(task_id):
    while True:
        time.sleep(3)  # Wait 3 seconds
        
        response = requests.get(
            f'https://api.apixo.ai/api/v1/statusTask/{MODEL}',
            params={'taskId': task_id},
            headers={'Authorization': f'Bearer {API_KEY}'},
        )
        
        result = response.json()['data']
        
        if result['state'] == 'success':
            import json
            urls = json.loads(result['resultJson'])['resultUrls']
            print(f'Generated images: {urls}')
            return urls
        
        if result['state'] == 'failed':
            raise Exception(result['failMsg'])
        
        print(f"Status: {result['state']}")

image_urls = poll_for_result(task_id)

Success Response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_abc123xyz",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://cdn.apixo.ai/generated/abc123.jpg\"]}",
    "costTime": 12500,
    "createTime": 1704067200000,
    "completeTime": 1704067212500
  }
}

Step 3: Download Your Image

The resultUrls array contains direct links to your generated images. Open the URL in a browser or download programmatically.

Generated images are available for 24 hours. Download and store important results.

Complete Example

Here’s a complete working example:

JavaScript
Python

const generateImage = async (prompt) => {
  const API_KEY = process.env.APIXO_API_KEY;
  const MODEL = 'nano-banana';
  
  // Submit
  const submit = await fetch(`https://api.apixo.ai/api/v1/generateTask/${MODEL}`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      request_type: 'async',
      input: { mode: 'text-to-image', prompt, aspect_ratio: '1:1' },
    }),
  });
  
  const { data: { taskId } } = await submit.json();
  
  // Poll
  while (true) {
    await new Promise(r => setTimeout(r, 3000));
    const status = await fetch(
      `https://api.apixo.ai/api/v1/statusTask/${MODEL}?taskId=${taskId}`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    );
    const { data } = await status.json();
    
    if (data.state === 'success') {
      return JSON.parse(data.resultJson).resultUrls;
    }
    if (data.state === 'failed') {
      throw new Error(data.failMsg);
    }
  }
};

// Usage
const urls = await generateImage('A cute robot drinking coffee');
console.log(urls);

import requests
import json
import time
import os

def generate_image(prompt: str) -> list[str]:
    api_key = os.environ['APIXO_API_KEY']
    model = 'nano-banana'
    base_url = 'https://api.apixo.ai/api/v1'
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json',
    }
    
    # Submit
    response = requests.post(
        f'{base_url}/generateTask/{model}',
        headers=headers,
        json={
            'request_type': 'async',
            'input': {'mode': 'text-to-image', 'prompt': prompt, 'aspect_ratio': '1:1'},
        }
    )
    task_id = response.json()['data']['taskId']
    
    # Poll
    while True:
        time.sleep(3)
        response = requests.get(
            f'{base_url}/statusTask/{model}',
            params={'taskId': task_id},
            headers=headers,
        )
        data = response.json()['data']
        
        if data['state'] == 'success':
            return json.loads(data['resultJson'])['resultUrls']
        if data['state'] == 'failed':
            raise Exception(data['failMsg'])

# Usage
urls = generate_image('A cute robot drinking coffee')
print(urls)

Next Steps

How APIXO Works

Learn the difference between Generation APIs and the Chat API

Generation API Overview

Browse image, video, and audio model API docs

Chat API

Use Claude, OpenAI, and Gemini compatible APIs

Best Practices

Optimize polling, retries, and production reliability

​Prerequisites

​Let your AI coding tool integrate APIXO for you

Connect APIXO MCP

​Step 1: Submit a Generation Task

​Step 2: Poll for Results

​Step 3: Download Your Image

​Complete Example

​Next Steps

How APIXO Works

Generation API Overview

Chat API

Best Practices

Prerequisites

Let your AI coding tool integrate APIXO for you

Step 1: Submit a Generation Task

Step 2: Poll for Results

Step 3: Download Your Image

Complete Example

Next Steps