Quickstart

Make your first APIXO Generation API request by authenticating, submitting an image task, polling its status, and retrieving the result URLs

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

Prerequisites

• An APIXO account (sign up free)
• Your API key (get one here)

Let your AI coding tool integrate APIXO for you

If you build with an AI coding tool — Cursor, Claude Code, Codex, Claude Desktop, Windsurf, or any other MCP-compatible client — the fastest way to add APIXO to your project is to install APIXO MCP. It exposes APIXO’s model catalog and schemas to your agent, so the agent can write correct, parameter-accurate integration code straight into your repo — instead of you reading the docs and copying curl examples.

Once installed, try a prompt like:

Use the apixo MCP tools. Add a server route to my Next.js app that calls the
nano-banana model to generate a 16:9 image from a `prompt` field in the request
body, and polls the status endpoint until the result URL is ready. Use my
existing fetch helpers and TypeScript types.

The agent will use apixo_list_models and apixo_get_model_schema to look up the model’s exact parameters, then write the generateTask + statusTask flow into your codebase. It can also submit ad-hoc tasks or check your balance when you ask it to.

Install APIXO MCP

Five-minute setup for Cursor, Claude Code, Codex, and other MCP clients on Windows, macOS, and Linux.

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

Step 1: Submit a Generation Task

cURL

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"
    }
  }'

JavaScript

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);

Python

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

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

JavaScript

// 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);

Python

# 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

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);

Python

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