API Reference

Reference conventions for the EggAPI public API

Base URL

text

https://api.eggapi.ai

Authentication

Use an API key from the dashboard:

text

Authorization: Bearer YOUR_API_KEY

Models

Pass a published model ID, such as google/nano-banana-2/text-to-image or bytedance/seedance-2.5/text-to-video, as model. See Models for the full list.

Request Format

Use HTTPS.
Send JSON bodies with Content-Type: application/json, except POST /v1/uploads, which takes multipart/form-data.
Include Authorization: Bearer YOUR_API_KEY.

Response Envelope

Success:

json

{
  "data": {},
  "error": null
}

Error:

json

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "request validation failed"
  }
}

Status Codes

Status	Meaning
`200`	Request succeeded.
`201`	Files were uploaded.
`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

Method	Path	Description
`POST`	`/v1/generate`	Create an image or video generation task. Body fields: Models.
`POST`	`/v1/uploads`	Upload input images, videos, or audio and get public URLs. See Uploads.
`GET`	`/v1/tasks/{id}`	Get one task with its status and output. See Async Tasks.
`GET`	`/v1/tasks`	List your tasks, newest first. See Async Tasks.
`GET`	`/v1/usage`	List usage records. See Usage.
`GET`	`/v1/usage/summary`	Usage totals grouped by model. See Usage.
`POST`	`/mcp`	MCP server for AI agents.

Usage

GET /v1/usage returns usage records under data.items, newest first, paginated with page and per_page. Each record has id, task_id, model, type, units, unit_cost, total_cost, status, and created_at.

GET /v1/usage/summary returns one row per model with model, total_units, total_cost, and request_count. See the example in the Quickstart.

OpenAPI

The OpenAPI spec describes every endpoint, request body, and response schema.

← Errors