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

# API 参考

> EggAPI 公开 API 的通用约定

## Base URL

```text theme={null}
https://api.eggapi.ai
```

## 鉴权

使用 dashboard 创建的 API Key：

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

## 公开模型范围

当前发布的公开目录只暴露 nano-banana。API 请求中请使用 `nanobanana` 作为 `model` 值。

## 请求格式

* 使用 HTTPS。
* JSON 请求体使用 `Content-Type: application/json`。
* 包含 `Authorization: Bearer YOUR_API_KEY`。

## 响应信封

成功：

```json theme={null}
{
  "data": {},
  "error": null
}
```

错误：

```json theme={null}
{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "request validation failed"
  }
}
```

## 状态码

| 状态 | 含义 |
| - | - |
| `200` | 请求成功。 |
| `202` | 已创建异步生成任务。 |
| `400` | 请求错误或参数校验失败。 |
| `401` | 缺少或无效凭证。 |
| `403` | 无权限或余额不足。 |
| `404` | 资源不存在。 |
| `429` | 触发限流。 |
| `500` | 后端内部错误。 |
| `502` | 上游供应商错误。 |
| `503` | 服务暂不可用。 |

## 分页

列表接口使用：

| 参数 | 默认 | 最大 |
| - | - | - |
| `page` | `1` | - |
| `per_page` | `20` | `100` |

分页响应会返回 `data.items` 和 `data.pagination`。

## 端点

<CardGroup cols={2}>
  <Card title="POST /v1/generate" href="/docs/zh/api-reference/introduction">
    创建 nano-banana 图片生成或图片编辑任务。
  </Card>

  <Card title="GET /v1/tasks/{id}" href="/docs/zh/api-reference/introduction">
    查询单个任务。
  </Card>

  <Card title="GET /v1/tasks" href="/docs/zh/api-reference/introduction">
    列出你的生成任务。
  </Card>

  <Card title="GET /v1/usage" href="/docs/zh/api-reference/introduction">
    列出用量记录。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.