# API-Key API Reference

API-Key is a multimodal API gateway for agents and developers. Use one API key
and one credit wallet to call chat, embeddings, image, video and music models.

## Machine-readable entrypoints

- OpenAPI: https://api-key.org/openapi.json
- API catalog: https://api-key.org/.well-known/api-catalog
- Model catalog: https://api-key.org/v1/models
- Credit estimate: https://api-key.org/v1/credits/estimate
- Auth.md: https://api-key.org/auth.md

## Authentication

Send a dashboard-created API key with every protected request:

```http
Authorization: Bearer YOUR_API_KEY
```

or:

```http
x-api-key: YOUR_API_KEY
```

## Budget guard

Agents should call `POST /v1/credits/estimate` before paid tasks. For actual
calls, pass `max_credits` in the JSON body to reject the request before a task
is created if the estimate is higher than the user's approved budget.

## Core endpoints

- `GET /v1/models`: list public models and capabilities.
- `POST /v1/credits/estimate`: estimate credits without charging.
- `POST /v1/chat/completions`: OpenAI-compatible chat.
- `POST /v1/embeddings`: OpenAI-compatible embeddings.
- `POST /v1/images/generations`: create async image tasks.
- `POST /v1/videos`: create async video tasks.
- `POST /v1/music/generations`: create async music tasks.
- `GET /v1/tasks/{task_id}`: poll async media task status and results.

## Minimal video flow

```bash
curl https://api-key.org/v1/credits/estimate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-fast",
    "modality": "video",
    "duration": 6,
    "resolution": "720p",
    "input_mode": "text-to-video",
    "max_credits": 250
  }'
```

```bash
curl https://api-key.org/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-fast",
    "prompt": "A cinematic product launch video with clean camera motion",
    "duration": 6,
    "resolution": "720p",
    "max_credits": 250,
    "callback_url": "https://your-app.com/webhooks/api-key"
  }'
```

Poll the returned `task_id`:

```bash
curl https://api-key.org/v1/tasks/task_abc123 \
  -H "Authorization: Bearer $API_KEY"
```

## Error shape

```json
{
  "error": {
    "message": "Insufficient credits",
    "type": "gateway_error",
    "code": "insufficient_credits"
  }
}
```