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

# NanoBanana API 快速入门

> 几分钟内开始使用 NanoBanana API。学习如何使用 AI 生成和编辑图像。

## 欢迎使用 NanoBanana API！

本快速入门指南将带您了解使用我们的 AI 模型开始生成和编辑图像的基本步骤。

## 概览

<CardGroup cols={2}>
  <Card title="生成图像" icon="wand-magic-sparkles" href="/cn/nanobanana-api/generate-or-edit-image">
    从文本描述创建 AI 图像或编辑现有图像
  </Card>

  <Card title="任务详情" icon="clock" href="/cn/nanobanana-api/get-task-details">
    查询任务状态并获取生成的图像结果
  </Card>
</CardGroup>

## 身份验证

所有 API 请求都需要通过 Bearer Token 进行身份验证。

<Steps>
  <Step title="获取您的 API 密钥">
    访问 [API密钥管理页面](https://nanobananaapi.ai/api-key) 获取您的API密钥。
  </Step>

  <Step title="添加到请求头">
    在所有请求中包含您的 API 密钥：

    ```bash theme={null}
    Authorization: Bearer YOUR_API_KEY
    ```
  </Step>
</Steps>

<Warning>
  保护您的 API 密钥安全，切勿公开分享。如果密钥被泄露，请立即在管理页面重置。
</Warning>

## 基本用法

### 1. 生成图像

首先创建您的第一个图像生成任务：

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.nanobananaapi.ai/api/v1/nanobanana/generate" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "美丽的山间日落风景",
      "type": "TEXTTOIAMGE",
      "numImages": 1,
      "callBackUrl": "https://your-callback-url.com/webhook"
    }'
  ```

  ```javascript Node.js theme={null}
  async function generateImage() {
    try {
      const response = await fetch('https://api.nanobananaapi.ai/api/v1/nanobanana/generate', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          prompt: '美丽的山间日落风景',
          type: 'TEXTTOIAMGE',
          numImages: 1,
          callBackUrl: 'https://your-callback-url.com/webhook'
        })
      });
      
      const result = await response.json();
      
      if (response.ok && result.code === 200) {
        console.log('任务已提交:', result);
        console.log('任务ID:', result.data.taskId);
        return result.data.taskId;
      } else {
        console.error('请求失败:', result.msg || '未知错误');
        return null;
      }
    } catch (error) {
      console.error('错误:', error.message);
      return null;
    }
  }

  generateImage();
  ```

  ```python Python theme={null}
  import requests

  def generate_image():
      url = "https://api.nanobananaapi.ai/api/v1/nanobanana/generate"
      headers = {
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json"
      }
      data = {
          "prompt": "美丽的山间日落风景",
          "type": "TEXTTOIAMGE",
          "numImages": 1,
          "callBackUrl": "https://your-callback-url.com/webhook"
      }
      
      try:
          response = requests.post(url, headers=headers, json=data)
          result = response.json()
          
          if response.ok and result.get('code') == 200:
              print(f"任务已提交: {result}")
              print(f"任务ID: {result['data']['taskId']}")
              return result['data']['taskId']
          else:
              print(f"请求失败: {result.get('msg', '未知错误')}")
              return None
      except requests.exceptions.RequestException as e:
          print(f"错误: {e}")
          return None

  generate_image()
  ```
</CodeGroup>

**响应：**

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task12345"
  }
}
```

### 2. 检查任务状态

使用返回的 `taskId` 来监控进度：

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.nanobananaapi.ai/api/v1/nanobanana/record-info?taskId=task12345" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  async function checkStatus(taskId) {
    try {
      const response = await fetch(`https://api.nanobananaapi.ai/api/v1/nanobanana/record-info?taskId=${taskId}`, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      });
      
      const result = await response.json();
      
      if (response.ok) {
        const taskData = result;
        
        switch (taskData.successFlag) {
          case 0:
            console.log('任务生成中...');
            break;
          case 1:
            console.log('任务成功完成！');
            console.log('结果图像:', taskData.response?.resultImageUrl);
            break;
          case 2:
            console.log('创建任务失败');
            break;
          case 3:
            console.log('生成失败');
            break;
        }
        return taskData;
      } else {
        console.error('查询失败');
        return null;
      }
    } catch (error) {
      console.error('状态检查失败:', error.message);
      return null;
    }
  }

  checkStatus('task12345');
  ```

  ```python Python theme={null}
  import requests

  def check_status(task_id):
      url = f"https://api.nanobananaapi.ai/api/v1/nanobanana/record-info?taskId={task_id}"
      headers = {"Authorization": "Bearer YOUR_API_KEY"}
      
      try:
          response = requests.get(url, headers=headers)
          result = response.json()
          
          if response.ok:
              success_flag = result.get('successFlag', 0)
              
              if success_flag == 0:
                  print("任务生成中...")
              elif success_flag == 1:
                  print("任务成功完成！")
                  result_url = result.get('response', {}).get('resultImageUrl', '')
                  print(f"结果图像: {result_url}")
              elif success_flag == 2:
                  print("创建任务失败")
              elif success_flag == 3:
                  print("生成失败")
              
              return result
          else:
              print("查询失败")
              return None
      except requests.exceptions.RequestException as e:
          print(f"状态检查失败: {e}")
          return None

  check_status('task12345')
  ```
</CodeGroup>

**状态值：**

* `0`: 生成中 - 任务正在处理中
* `1`: 成功 - 任务成功完成
* `2`: 创建任务失败 - 任务创建失败
* `3`: 生成失败 - 任务创建成功但生成失败

## 完整示例

这是一个完整的工作流程示例：

<CodeGroup>
  ```javascript JavaScript theme={null}
  class NanoBananaAPI {
    constructor(apiKey) {
      this.apiKey = apiKey;
      this.baseUrl = 'https://api.nanobananaapi.ai/api/v1/nanobanana';
    }
    
    async generateImage(prompt, options = {}) {
      const response = await fetch(`${this.baseUrl}/generate`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          prompt,
          type: options.type || 'TEXTTOIAMGE',
          numImages: options.numImages || 1,
          callBackUrl: options.callBackUrl,
          watermark: options.watermark,
          imageUrls: options.imageUrls
        })
      });
      
      const result = await response.json();
      if (!response.ok || result.code !== 200) {
        throw new Error(`生成失败: ${result.msg || '未知错误'}`);
      }
      
      return result.data.taskId;
    }
    
    async getTaskStatus(taskId) {
      const response = await fetch(`${this.baseUrl}/record-info?taskId=${taskId}`, {
        method: 'GET',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`
        }
      });
      
      const result = await response.json();
      return result;
    }
    
    async waitForCompletion(taskId, maxWaitTime = 300000) {
      const startTime = Date.now();
      
      while (Date.now() - startTime < maxWaitTime) {
        const status = await this.getTaskStatus(taskId);
        
        switch (status.successFlag) {
          case 0:
            console.log('任务生成中...');
            break;
          case 1:
            console.log('生成成功完成！');
            return status.response;
          case 2:
          case 3:
            throw new Error(status.errorMessage || '生成失败');
        }
        
        await new Promise(resolve => setTimeout(resolve, 3000));
      }
      
      throw new Error('生成超时');
    }
  }

  // 使用示例
  async function main() {
    const api = new NanoBananaAPI('YOUR_API_KEY');
    
    try {
      console.log('开始图像生成...');
      const taskId = await api.generateImage('美丽的风景画');
      
      console.log(`任务ID: ${taskId}。等待完成中...`);
      const result = await api.waitForCompletion(taskId);
      
      console.log('图像生成成功！');
      console.log('结果图像URL:', result.resultImageUrl);
      
    } catch (error) {
      console.error('错误:', error.message);
    }
  }

  main();
  ```

  ```python Python theme={null}
  import requests
  import time

  class NanoBananaAPI:
      def __init__(self, api_key):
          self.api_key = api_key
          self.base_url = 'https://api.nanobananaapi.ai/api/v1/nanobanana'
          self.headers = {
              'Authorization': f'Bearer {api_key}',
              'Content-Type': 'application/json'
          }
      
      def generate_image(self, prompt, **options):
          data = {
              'prompt': prompt,
              'type': options.get('type', 'TEXTTOIAMGE'),
              'numImages': options.get('numImages', 1),
              'callBackUrl': options.get('callBackUrl'),
              'watermark': options.get('watermark')
          }
          
          if options.get('imageUrls'):
              data['imageUrls'] = options['imageUrls']
          
          response = requests.post(f'{self.base_url}/generate', 
                                 headers=self.headers, json=data)
          result = response.json()
          
          if not response.ok or result.get('code') != 200:
              raise Exception(f"生成失败: {result.get('msg', '未知错误')}")
          
          return result['data']['taskId']
      
      def get_task_status(self, task_id):
          response = requests.get(f'{self.base_url}/record-info?taskId={task_id}',
                                headers={'Authorization': f'Bearer {self.api_key}'})
          return response.json()
      
      def wait_for_completion(self, task_id, max_wait_time=300):
          start_time = time.time()
          
          while time.time() - start_time < max_wait_time:
              status = self.get_task_status(task_id)
              success_flag = status.get('successFlag', 0)
              
              if success_flag == 0:
                  print("任务生成中...")
              elif success_flag == 1:
                  print("生成成功完成！")
                  return status.get('response', {})
              elif success_flag in [2, 3]:
                  error_msg = status.get('errorMessage', '生成失败')
                  raise Exception(error_msg)
              
              time.sleep(3)
          
          raise Exception('生成超时')

  # 使用示例
  def main():
      api = NanoBananaAPI('YOUR_API_KEY')
      
      try:
          print('开始图像生成...')
          task_id = api.generate_image('美丽的风景画')
          
          print(f'任务ID: {task_id}。等待完成中...')
          result = api.wait_for_completion(task_id)
          
          print('图像生成成功！')
          print(f'结果图像URL: {result.get("resultImageUrl", "")}')
          
      except Exception as error:
          print(f'错误: {error}')

  if __name__ == '__main__':
      main()
  ```
</CodeGroup>

## 参数说明

### 必需参数

| 参数            | 类型     | 描述                                  |
| ------------- | ------ | ----------------------------------- |
| `prompt`      | string | 图像生成的文本描述                           |
| `type`        | string | 生成类型：`TEXTTOIAMGE` 或 `IMAGETOIAMGE` |
| `callBackUrl` | string | Webhook 回调 URL                      |

### 可选参数

| 参数          | 类型      | 描述            | 默认值 |
| ----------- | ------- | ------------- | --- |
| `numImages` | integer | 生成图像数量 (1-4)  | 1   |
| `imageUrls` | array   | 用于编辑的输入图像 URL | -   |
| `watermark` | string  | 生成图像的水印文字     | -   |

## 下一步

<CardGroup cols={2}>
  <Card title="生成图像" icon="image" href="/cn/nanobanana-api/generate-or-edit-image">
    了解所有生成参数和高级选项
  </Card>

  <Card title="查看账户积分" icon="credit-card" href="/cn/common-api/get-account-credits">
    监控您的账户积分余额
  </Card>
</CardGroup>

## 支持

需要帮助？联系我们的技术支持：

* **技术支持**: [support@nanobanana.com](mailto:support@nanobananaapi.ai)

准备好创建惊人的 AI 图像了吗？从上面的示例开始，探索完整的 API 功能！