> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/api-reference/introduction/use.md).

# Usage

### Endpoints

| Method | Path                                               | Description                                                                          |
| ------ | -------------------------------------------------- | ------------------------------------------------------------------------------------ |
| GET    | `/api/compat/v1/usage`                             | List generation records from `generations` table                                     |
| GET    | `/api/compat/v1/balance`                           | Get current credit balance of authenticated user                                     |
| GET    | `/api/compat/v1/api-key`                           | Look up the calling API key's name, status, and spend limits                         |
| POST   | `/api/v1/image/estimate`                           | Preview `usdCost` for an image generation request before submitting it               |
| POST   | `/api/v1/video/estimate`                           | Preview `usdCost` for a video generation request before submitting it                |
| POST   | `/api/v1/audio/text-to-speech/estimate`            | Preview `usdCost` for a Text-to-Speech request before submitting it                  |
| POST   | `/api/v1/audio/generation-with-reference/estimate` | Preview `usdCost` for a Generation-With-Reference audio request before submitting it |

Auth: `Authorization: Bearer <your-api-key>` or `x-api-key`.

The four `estimate` endpoints live on the native API (`/api/v1`), not the compat surface (`/api/compat/v1`) — see Estimating Cost Before Generating below.

### GET /api/compat/v1/usage

Query fields:

| Field    | Type     | Required | Notes        |
| -------- | -------- | -------- | ------------ |
| `offset` | `number` | No       | Default `0`  |
| `limit`  | `number` | No       | Default `20` |

Response shape:

| Field                  | Type                                                  |
| ---------------------- | ----------------------------------------------------- |
| `results[]`            | Array of generation rows                              |
| `results[].id`         | `string`                                              |
| `results[].userId`     | `string`                                              |
| `results[].apiKeyId`   | `string \| undefined`                                 |
| `results[].modality`   | `"text" \| "image" \| "video" \| "audio"`             |
| `results[].model`      | `string`                                              |
| `results[].status`     | `"succeeded" \| "failed" \| "aborted" \| "cancelled"` |
| `results[].usage`      | `object \| undefined`                                 |
| `results[].usdCost`    | `number \| undefined`                                 |
| `results[].durationMs` | `number \| undefined`                                 |
| `results[].createdAt`  | `datetime`                                            |
| `total`                | `number`                                              |
| `offset`               | `number`                                              |
| `limit`                | `number`                                              |

This endpoint currently supports paging only and returns compat generation rows.

#### Response Example

```json
{
	"results": [
		{
			"id": "6a584d837deb305999dda675",
			"userId": "6a38e2554301a757f3721c0c",
			"modality": "image",
			"model": "seedream-4-0",
			"status": "succeeded",
			"usage": {
				"totalTokens": 14400,
				"generatedImages": 1,
				"outputTokens": 14400
			},
			"usdCost": 0.036,
			"durationMs": 6256,
			"createdAt": "2026-07-16T03:18:27.208Z"
		}
	],
	"total": 1,
	"offset": 0,
	"limit": 20
}
```

### How Tokens and Credits Are Calculated

#### Tokens (`usage`)

`usage` fields are normalized from runtime usage and stored per generation row.

* Text: commonly includes `promptTokens`, `completionTokens`, and `totalTokens`.
* Image: commonly includes `generatedImages`, `outputTokens`, and sometimes `totalTokens`.
* Video: commonly includes `completionTokens` / `totalTokens` when available from provider.

Token fields can vary by model and request type, so not every key is guaranteed on every row.

#### Credits (`usdCost`)

`usdCost` is the final user charge for that generation row.

At settle time, the backend computes the final billable amount using your account pricing policy.

Formula summary:

```
usdCost = final billable amount for this generation
```

In usage records, `usdCost` is the amount deducted for that request.

### Estimating Cost Before Generating

Before submitting an image, video, or audio generation request, you can preview the `usdCost` it will produce in `GET /api/compat/v1/usage` by calling the matching estimate endpoint on the native API (`/api/v1`, not `/api/compat/v1`). No credit is deducted and nothing is persisted.

| Modality                          | Estimate endpoint                                       | Request body                                           |
| --------------------------------- | ------------------------------------------------------- | ------------------------------------------------------ |
| Image                             | `POST /api/v1/image/estimate`                           | Same as `POST /api/v1/image/generations`               |
| Video                             | `POST /api/v1/video/estimate`                           | Same as `POST /api/v1/video/generations`               |
| Audio (Text-to-Speech)            | `POST /api/v1/audio/text-to-speech/estimate`            | Same as `POST /api/v1/audio/text-to-speech`            |
| Audio (Generation With Reference) | `POST /api/v1/audio/generation-with-reference/estimate` | Same as `POST /api/v1/audio/generation-with-reference` |

Every estimate endpoint returns the same shape — `{ estimatedUserCost, currency }` wrapped in the standard response envelope — for the same request body its matching generation endpoint accepts. `estimatedUserCost` is denominated the same way as `usdCost` in usage rows above.

* **Image and Text-to-Speech audio**: the estimate is exact — it matches what settles into `usdCost`, since the billable unit (image count, character count) is fully known from the request.
* **Video and Generation-With-Reference audio**: the estimate is indicative only. Both bill by output duration, which providers only report after generation completes, so the settled `usdCost` can differ from the estimate.

#### Image

See [Image Generation § Estimate Cost](https://docs.avis.net/api-reference/endpoints/image-generation#estimate-cost) for full request/response details.

```
POST /api/v1/image/estimate
```

```json
{
  "model": "seedream-4-0",
  "content": [
    { "type": "text", "text": "Create two clean product mockup images on a neutral background." }
  ],
  "size": "1024x1024",
  "numberOfImages": 2,
  "watermark": false
}
```

```json
{
  "data": { "estimatedUserCost": 0.12, "currency": "USD" },
  "success": true,
  "status": 200
}
```

#### Video

See [Video Generation § Estimate Cost](https://docs.avis.net/api-reference/endpoints/video-generation#estimate-cost) for full request/response details.

```
POST /api/v1/video/estimate
```

```json
{
  "model": "wan-2-6",
  "content": [
    { "type": "text", "text": "Smooth interpolation between the two frames" },
    { "type": "imageUrl", "url": "https://example.com/first.jpeg", "role": "firstFrame" },
    { "type": "imageUrl", "url": "https://example.com/last.jpeg", "role": "lastFrame" }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "generateAudio": false
}
```

```json
{
  "data": { "estimatedUserCost": 0.51, "currency": "USD" },
  "success": true,
  "status": 200
}
```

#### Audio — Text-to-Speech

See [Audio Generation § Estimate Cost § Text-to-Speech](https://docs.avis.net/api-reference/endpoints/audio-generation#text-to-speech-1) for full request/response details.

```
POST /api/v1/audio/text-to-speech/estimate
```

```json
{
  "voiceType": "en_female_dacey_uranus_bigtts",
  "text": "Hello, welcome to our platform. We are glad to have you here."
}
```

```json
{
  "data": { "estimatedUserCost": 0.002, "currency": "USD" },
  "success": true,
  "status": 200
}
```

#### Audio — Generation With Reference

See [Audio Generation § Estimate Cost § Generation With Reference](https://docs.avis.net/api-reference/endpoints/audio-generation#generation-with-reference-1) for full request/response details.

```
POST /api/v1/audio/generation-with-reference/estimate
```

```json
{
  "model": "seed-audio-1.0-multilingual",
  "textPrompt": "A warm audiobook narrator reading: The sun was setting over the mountain ridge."
}
```

```json
{
  "data": { "estimatedUserCost": 0.015, "currency": "USD" },
  "success": true,
  "status": 200
}
```

### GET /api/compat/v1/balance

Response shape:

| Field           | Type     |
| --------------- | -------- |
| `creditBalance` | `number` |

Response example:

```json
{
	"creditBalance": 12.345
}
```

### GET /api/compat/v1/api-key

Looks up the calling API key's name, status, and configured spend caps (daily/weekly/monthly/total).

**Auth: `x-api-key` only.** This endpoint reports on *the specific key used to authenticate the request*, so a JWT-authenticated session (no key attached) returns `403`.

The response is scoped to the key itself and deliberately excludes the owning account's credit balance — a key holder is not necessarily the account owner. Use `GET /api/compat/v1/balance` for the account balance.

Response shape:

| Field                                   | Type                  | Notes                                                                                                                            |
| --------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                  | `string`              | The key's display name.                                                                                                          |
| `isActive`                              | `boolean`             | Always `true` when this call succeeds — a disabled/revoked key fails auth before reaching this endpoint.                         |
| `daily`                                 | `object \| undefined` | Present only if a daily cap is configured.                                                                                       |
| `weekly`                                | `object \| undefined` | Present only if a weekly cap is configured.                                                                                      |
| `monthly`                               | `object \| undefined` | Present only if a monthly cap is configured.                                                                                     |
| `total`                                 | `object \| undefined` | Present only if a lifetime cap is configured.                                                                                    |
| `daily.limit` / `.spent` / `.remaining` | `number`              | Cap, amount spent in the current window, and remaining capacity — all in credits. `remaining` is clamped to `0`, never negative. |

Every cap field (`daily`/`weekly`/`monthly`/`total`) shares the same `{ limit, spent, remaining }` shape. A key with no caps configured omits all four fields entirely.

#### Response Example

```json
{
	"name": "my-production-key",
	"isActive": true,
	"daily": { "limit": 100, "spent": 40, "remaining": 60 },
	"monthly": { "limit": 2000, "spent": 500, "remaining": 1500 }
}
```

### Reference: `usage` By Modality (From `generations`)

Based on current real records, the `usage` payload is modality-specific.

#### Text

Typical fields:

| Field                    | Type     |
| ------------------------ | -------- |
| `usage.promptTokens`     | `number` |
| `usage.completionTokens` | `number` |
| `usage.totalTokens`      | `number` |

#### Image

Typical fields:

| Field                   | Type     |
| ----------------------- | -------- |
| `usage.generatedImages` | `number` |
| `usage.inputTokens`     | `number` |
| `usage.outputTokens`    | `number` |
| `usage.totalTokens`     | `number` |

#### Video

Typical fields:

| Field                    | Type     |
| ------------------------ | -------- |
| `usage.completionTokens` | `number` |
| `usage.totalTokens`      | `number` |

The exact `usage` keys can vary by model and request type.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.avis.net/api-reference/introduction/use.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.