# Common API

These endpoints support model discovery, integration checks and media task retrieval. The examples use the current brand’s API origin. Protected requests use `Authorization: Bearer $API_KEY`.

| Endpoint | Purpose | Authentication |
| --- | --- | --- |
| `GET /v1/models` | Currently callable LLM models and native protocols | Public |
| `GET /v1/media-models` | Enabled media models, input schemas and public price configuration | Public |
| `GET /v1/balance` | API key owner's account points balance | Bearer API key |
| `GET /v1/tasks/{task_id}` | Retrieve one media task | Bearer API key |

All response examples show selected fields with illustrative values and IDs.

## Discover models

### LLM models

```bash
curl "https://newrouters.com/v1/models"
```

```json
{
  "data": [
    { "id": "MODEL_ID", "model": "MODEL_ID", "protocol": "openai" }
  ]
}
```

Use the returned `id` / `model` exactly. The `protocol` is `openai`, `claude` or `gemini`; follow the model's native request format. Entries also include `capabilities`, `context_limit` and `max_output_tokens`. The public catalog reflects current supply, but does not grant your API key access to every listed model.

### Media models and parameters

```bash
curl "https://newrouters.com/v1/media-models"
```

```json
{
  "data": [
    {
      "model": "MODEL_ID",
      "type": "image",
      "contract_version": 1,
      "request_schema": { "type": "object" }
    }
  ]
}
```

Lists enabled image, video or audio models, including `display_name`, `description`, `request_schema` and `pricing`. The schema describes task **input**, not the complete `model + input` envelope. Check required fields, enum values and constraints; public price configuration does not replace your account's actual prices.

## Check balance

```bash
curl "https://newrouters.com/v1/balance" \
  -H "Authorization: Bearer $API_KEY"
```

HTTP `200`:

```json
{ "points": "123.456789" }
```

| Field | Type | Meaning |
| --- | --- | --- |
| `points` | decimal string | Points belonging to the API key owner's account |

This is the account's points balance, not a currency amount or an individual key's remaining limit. The response is directly `{ "points": "..." }`, without a `data` wrapper. Missing or invalid keys return `401`; a missing account returns `404`. Preserve decimal precision when processing points.

## Retrieve tasks

### One task

```bash
curl "https://newrouters.com/v1/tasks/TASK_ID" \
  -H "Authorization: Bearer $API_KEY"
```

Replace `TASK_ID` with the creation response's `id`, not an upstream task ID. HTTP `200` means retrieval succeeded; inspect `status` to determine generation progress.

```json
{
  "id": "TASK_ID",
  "status": "succeeded",
  "model": "MODEL_ID",
  "result": { "assets": ["https://example.com/output.png"] },
  "error": null
}
```

| status | Action |
| --- | --- |
| `pending` | Accepted; poll the same task |
| `processing` | Processing; poll the same task |
| `succeeded` | Read asset URLs from `result.assets[]` |
| `failed` | Read `error.code` and `error.message` |

The full response also includes type, request, point estimates and settlement fields, plus timestamps. Use a key belonging to the creating account. The creation endpoint's `202` does not mean generation completed.

`/v1/account/*` endpoints belong to the session-authenticated dashboard; do not assume they accept Bearer API keys. For example, `/v1/account/billing/usage` requires a login session. Server-side balance checks use `/v1/balance` above.

[Quickstart](/docs/quickstart) · [Model guides](/docs)