> ## 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

> Submit your first APIXO generation task and retrieve the result

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](/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="/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="/concepts/how-apixo-works">
    Learn the difference between Generation APIs and the LLM Gateway
  </Card>

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

  <Card title="LLM Gateway" href="/llm">
    Use Claude, OpenAI, and Gemini compatible APIs
  </Card>

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