> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://apixo.ai))
* Your API key ([get one here](/docs/concepts/authentication))

## 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](https://modelcontextprotocol.io) 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:

```text theme={null}
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.

<Card title="Install APIXO MCP" icon="plug" href="/docs/integrations/mcp/installation">
  Five-minute setup for Cursor, Claude Code, Codex, and other MCP clients on Windows, macOS, and Linux.
</Card>

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

## Step 1: Submit a Generation Task

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    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"
        }
      }'
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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}')
    ```
  </Tab>
</Tabs>

**Response:**

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_abc123xyz"
  }
}
```

## Step 2: Poll for Results

Wait a few seconds, then check the task status:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.apixo.ai/api/v1/statusTask/nano-banana?taskId=task_abc123xyz" \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    // 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);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # 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)
    ```
  </Tab>
</Tabs>

**Success Response:**

```json theme={null}
{
  "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.

<Info>
  Generated images are available for 24 hours. Download and store important results.
</Info>

## Complete Example

Here's a complete working example:

<Tabs>
  <Tab title="JavaScript">
    ```javascript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup>
  <Card title="How APIXO Works" href="/docs/concepts/how-apixo-works">
    Learn the difference between Generation APIs and the Chat API
  </Card>

  <Card title="Generation API Overview" href="/docs/models">
    Browse image, video, and audio model API docs
  </Card>

  <Card title="Chat API" href="/docs/llm">
    Use Claude, OpenAI, and Gemini compatible APIs
  </Card>

  <Card title="Best Practices" href="/docs/guides/best-practices">
    Optimize polling, retries, and production reliability
  </Card>
</CardGroup>