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

> Reference conventions for the EggAPI public API

## Base URL

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

## Authentication

Use an API key from the dashboard:

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

## Public Model Scope

The current published public catalog exposes only nano-banana. Use `nanobanana` as the `model` value in API requests.

## Request Format

* Use HTTPS.
* Send JSON bodies with `Content-Type: application/json`.
* Include `Authorization: Bearer YOUR_API_KEY`.

## Response Envelope

Success:

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

Error:

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

## Status Codes

| Status | Meaning                            |
| ------ | ---------------------------------- |
| `200`  | Request succeeded.                 |
| `202`  | Async generation task was created. |
| `400`  | Bad request or validation error.   |
| `401`  | Missing or invalid credentials.    |
| `403`  | Forbidden or insufficient balance. |
| `404`  | Resource not found.                |
| `429`  | Rate limited.                      |
| `500`  | Internal backend error.            |
| `502`  | Upstream provider error.           |
| `503`  | Service unavailable.               |

## Pagination

List endpoints use:

| Parameter  | Default | Max   |
| ---------- | ------- | ----- |
| `page`     | `1`     | -     |
| `per_page` | `20`    | `100` |

Paginated responses return `data.items` and `data.pagination`.

## Endpoints

<CardGroup cols={2}>
  <Card title="POST /v1/generate" href="/docs/en/api-reference/introduction">
    Create a nano-banana image generation or image editing task.
  </Card>

  <Card title="GET /v1/tasks/{id}" href="/docs/en/api-reference/introduction">
    Get one task by ID.
  </Card>

  <Card title="GET /v1/tasks" href="/docs/en/api-reference/introduction">
    List your generation tasks.
  </Card>

  <Card title="GET /v1/usage" href="/docs/en/api-reference/introduction">
    List usage records.
  </Card>
</CardGroup>