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

# API Overview

> Complete reference for the Firemoon Studio API endpoints

## Base URL

```
https://firemoon.studio/api
```

Most API requests require authentication using an API key in the Authorization header:

```
Authorization: Bearer YOUR_API_KEY
```

<Note>
  Some endpoints like `/api/models` and `/api/models-config/*` are public and don't require authentication.
</Note>

## Endpoints

### Generation Endpoints

| Method | Endpoint            | Description                             | Auth Required |
| ------ | ------------------- | --------------------------------------- | ------------- |
| `POST` | `/api/v1/{modelid}` | Generate content using a specific model | Yes           |

### Account & Usage Endpoints

| Method | Endpoint               | Description                        | Auth Required |
| ------ | ---------------------- | ---------------------------------- | ------------- |
| `GET`  | `/api/credits/balance` | Get your current credit balance    | Yes           |
| `GET`  | `/api/generations`     | Get your generation history        | Yes           |
| `GET`  | `/api/usage`           | Get usage statistics and analytics | Yes           |

## Response Format

All generation endpoints return a consistent response structure:

```json theme={null}
{
  "images": [
    {
      "url": "https://blob.vercel-storage.com/...",
      "width": 1024,
      "height": 768,
      "content_type": "image/jpeg"
    }
  ],
  "seed": 123456789,
  "has_nsfw_concepts": [false],
  "timings": {
    "inference": 2.5
  }
}
```

For video generation, the response includes video URLs instead of images:

```json theme={null}
{
  "videos": [
    {
      "url": "https://blob.vercel-storage.com/...",
      "duration": 5,
      "width": 1920,
      "height": 1088,
      "content_type": "video/mp4"
    }
  ],
  "seed": 123456789,
  "timings": {
    "inference": 15.2
  }
}
```

## Error Responses

### 401 Unauthorized

```json theme={null}
{
  "error": "Invalid API key",
  "message": "Please provide a valid API key in the Authorization header"
}
```

### 403 Forbidden

```json theme={null}
{
  "error": "Access denied",
  "message": "Your API key does not have access to provider: flux"
}
```

### 404 Not Found

```json theme={null}
{
  "error": "Model not found",
  "message": "Model configuration not found for flux/invalid-model"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "error": "Rate limit exceeded",
  "message": "Rate limit exceeded. Try again in 45 seconds.",
  "resetAt": "2025-10-23T10:30:00.000Z"
}
```

### 400 Bad Request

```json theme={null}
{
  "error": "Invalid input",
  "message": "Input validation failed",
  "errors": [
    "Missing required field: prompt"
  ]
}
```

### 402 Payment Required

```json theme={null}
{
  "error": "Insufficient credits",
  "message": "Insufficient credits to generate content"
}
```

**Common causes:**

* Credit balance is too low for the requested operation
* Cost exceeds available balance

### 500 Internal Server Error

```json theme={null}
{
  "error": "Generation failed",
  "message": "Failed to generate image: timeout"
}
```