|
| 1 | +--- |
| 2 | +icon: list-tree |
| 3 | +--- |
| 4 | + |
| 5 | +# Model Catalogue API |
| 6 | + |
| 7 | +## List models |
| 8 | + |
| 9 | +`GET /v1/models` returns the live catalogue. It is the machine-readable source for which models exist, what they are called, what they can do, and what they cost — use it instead of scraping the model pages. |
| 10 | + |
| 11 | +By default each entry carries only its identity. Pricing, modalities and capabilities are opt-in, so the default response stays small: |
| 12 | + |
| 13 | +```bash |
| 14 | +curl https://api.aimlapi.com/v1/models |
| 15 | +``` |
| 16 | + |
| 17 | +```json |
| 18 | +{ |
| 19 | + "object": "list", |
| 20 | + "data": [ |
| 21 | + { |
| 22 | + "id": "deepgram/aura-2", |
| 23 | + "aliases": ["aura-2", "aura-2-helena-en", "deepgram/aura-2-helena-en"], |
| 24 | + "type": "internal/text-to-speech", |
| 25 | + "info": { "name": "Aura-2", "developer": "Deepgram" }, |
| 26 | + "tags": ["playground:tts"] |
| 27 | + } |
| 28 | + ] |
| 29 | +} |
| 30 | +``` |
| 31 | + |
| 32 | +{% openapi-operation spec="models-catalogue" path="/v1/models" method="get" %} |
| 33 | +[OpenAPI models-catalogue](https://raw.githubusercontent.com/aimlapi/api-docs/refs/heads/main/docs/service-endpoints/models-catalogue.json) |
| 34 | +{% endopenapi-operation %} |
| 35 | + |
| 36 | +## Asking for more per model |
| 37 | + |
| 38 | +`include` attaches optional sections. Combine them freely, comma-separated: |
| 39 | + |
| 40 | +```bash |
| 41 | +curl 'https://api.aimlapi.com/v1/models?include=pricing' |
| 42 | +curl 'https://api.aimlapi.com/v1/models?include=pricing,capabilities' |
| 43 | +curl 'https://api.aimlapi.com/v1/models?include=all' |
| 44 | +``` |
| 45 | + |
| 46 | +| Value | Adds | |
| 47 | +| --- | --- | |
| 48 | +| `pricing` | the `pricing` block — rates, units, price bands | |
| 49 | +| `modalities` | which input and output modalities the model handles | |
| 50 | +| `capabilities` | declared capabilities, e.g. `image_to_video` | |
| 51 | +| `all` | every section. `?details=true` is a synonym | |
| 52 | + |
| 53 | +Unknown values are ignored rather than rejected, so a typo returns a valid response with that section missing. |
| 54 | + |
| 55 | +## Filtering |
| 56 | + |
| 57 | +Every filter below narrows *which models* come back. They are independent of `include`, so you can filter on capabilities without asking for the capabilities section. |
| 58 | + |
| 59 | +| Parameter | Keeps models that… | |
| 60 | +| --- | --- | |
| 61 | +| `id` | match this id **or carry it as an alias** | |
| 62 | +| `type` | are served through this endpoint type | |
| 63 | +| `tags` | carry this tag, e.g. `playground:video` | |
| 64 | +| `modalities` | have it among input **or** output modalities | |
| 65 | +| `input_modalities` | accept this input modality | |
| 66 | +| `output_modalities` | produce this output modality | |
| 67 | +| `capabilities` | declare this capability | |
| 68 | + |
| 69 | +Rules that apply to all of them: |
| 70 | + |
| 71 | +* **Several values, one parameter — OR.** `?capabilities=text_to_video,image_to_video` returns models that do either. |
| 72 | +* **Several parameters — AND.** `?output_modalities=video&capabilities=audio_generation` returns models that do both. |
| 73 | +* Values are **case-insensitive**, and may be given comma-separated (`?tags=a,b`) or repeated (`?tags=a&tags=b`). Both forms merge. |
| 74 | +* An omitted parameter filters nothing. |
| 75 | + |
| 76 | +```bash |
| 77 | +# every model that turns an image into video |
| 78 | +curl 'https://api.aimlapi.com/v1/models?capabilities=image_to_video' |
| 79 | + |
| 80 | +# what one specific model costs — a few kilobytes instead of the whole catalogue |
| 81 | +curl 'https://api.aimlapi.com/v1/models?id=deepgram/aura-2&include=pricing' |
| 82 | +``` |
| 83 | + |
| 84 | +## Checking whether a model is still available |
| 85 | + |
| 86 | +Match against **`id` and `aliases` together**. A model may be published under a canonical id while the name you integrated against lives on as an alias — the alias keeps working, but it is not the `id` any more, so an `id`-only comparison reports a live model as gone. |
| 87 | + |
| 88 | +```js |
| 89 | +const res = await fetch('https://api.aimlapi.com/v1/models'); |
| 90 | +const { data } = await res.json(); |
| 91 | + |
| 92 | +const byName = new Map(); |
| 93 | +for (const model of data) { |
| 94 | + byName.set(model.id, model.id); |
| 95 | + for (const alias of model.aliases ?? []) byName.set(alias, model.id); |
| 96 | +} |
| 97 | + |
| 98 | +const canonical = byName.get(myModelId); // undefined ⇒ genuinely unavailable |
| 99 | +``` |
| 100 | +
|
| 101 | +The same map de-duplicates your list: two names resolving to one canonical id are one model, not two. |
| 102 | +
|
| 103 | +## Reading prices |
| 104 | +
|
| 105 | +With `?include=pricing`, each model carries a `pricing` block. Read `kind` first: |
| 106 | +
|
| 107 | +| `kind` | What it means | |
| 108 | +| --- | --- | |
| 109 | +| `fixed` | one rate per unit, in `units[]` | |
| 110 | +| `variants` | the rate depends on request parameters — `dimensions` names them, `variants[]` quotes a rate per combination | |
| 111 | +| `variable` | the rate cannot be quoted ahead of the request | |
| 112 | +
|
| 113 | +**Always read `per` together with `price`.** `price` is the charge for `per` units, and `per` is not the same across models — `1000000` for most token rates, `1000` for some, `1` for per-second and per-megapixel rates. Comparing bare `price` values across models compares different bases and will be wrong by orders of magnitude. |
| 114 | +
|
| 115 | +```json |
| 116 | +{ |
| 117 | + "kind": "variants", |
| 118 | + "dimensions": ["resolution"], |
| 119 | + "variants": [ |
| 120 | + { "when": { "resolution": "720p" }, "price": 0.39, "unit": "second", "per": 1 }, |
| 121 | + { "when": { "resolution": "1080p" }, "price": 0.65, "unit": "second", "per": 1 } |
| 122 | + ] |
| 123 | +} |
| 124 | +``` |
| 125 | +
|
| 126 | +Here a 5-second 1080p generation costs `0.65 × 5 = $3.25`. |
| 127 | +
|
| 128 | +Prices are in USD and are what you are charged. |
| 129 | +
|
| 130 | +## Caching |
| 131 | +
|
| 132 | +Responses carry an `ETag`. Send it back as `If-None-Match` and you get `304 Not Modified` with an empty body when nothing changed: |
| 133 | +
|
| 134 | +```bash |
| 135 | +curl -I 'https://api.aimlapi.com/v1/models?include=pricing' |
| 136 | +# etag: W/"1440a0-uH6NONsG/9An5njw3kqMcYY5k8w" |
| 137 | + |
| 138 | +curl -H 'If-None-Match: W/"1440a0-uH6NONsG/9An5njw3kqMcYY5k8w"' \ |
| 139 | + 'https://api.aimlapi.com/v1/models?include=pricing' |
| 140 | +# 304 |
| 141 | +``` |
| 142 | +
|
| 143 | +The ETag covers the whole response, so it changes on any catalogue edit — a new model or a reworded description, not only a price change. Treat it as "something moved, re-read and diff", not as a price-change feed. |
0 commit comments