diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index e7b7603f..175610ef 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -13,7 +13,6 @@ * [🟑 Service Endpoints](api-references/service-endpoints/README.md) * [Account Balance](api-references/service-endpoints/account-balance.md) - * [Model Catalogue API](api-references/service-endpoints/models-catalogue.md) * [API Key Management](api-references/service-endpoints/api-key-management.md) * [API Key Usage](api-references/service-endpoints/api-key-usage.md) * [Complete Model List](api-references/service-endpoints/complete-model-list.md) diff --git a/docs/api-references/service-endpoints/models-catalogue.md b/docs/api-references/service-endpoints/models-catalogue.md deleted file mode 100644 index 5eb80efa..00000000 --- a/docs/api-references/service-endpoints/models-catalogue.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -icon: list-tree ---- - -# Model Catalogue API - -## List models - -`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. - -By default each entry carries only its identity. Pricing, modalities and capabilities are opt-in, so the default response stays small: - -```bash -curl https://api.aimlapi.com/v1/models -``` - -```json -{ - "object": "list", - "data": [ - { - "id": "deepgram/aura-2", - "aliases": ["aura-2", "aura-2-helena-en", "deepgram/aura-2-helena-en"], - "type": "internal/text-to-speech", - "info": { "name": "Aura-2", "developer": "Deepgram" }, - "tags": ["playground:tts"] - } - ] -} -``` - -{% openapi-operation spec="models-catalogue" path="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/v1/models" method="get" %} -[OpenAPI models-catalogue](https://raw.githubusercontent.com/aimlapi/api-docs/refs/heads/main/docs/service-endpoints/models-catalogue.json) -{% endopenapi-operation %} - -## Asking for more per model - -`include` attaches optional sections. Combine them freely, comma-separated: - -```bash -curl 'https://api.aimlapi.com/v1/models?include=pricing' -curl 'https://api.aimlapi.com/v1/models?include=pricing,capabilities' -curl 'https://api.aimlapi.com/v1/models?include=all' -``` - -| Value | Adds | -| --- | --- | -| `pricing` | the `pricing` block β€” rates, units, price bands | -| `modalities` | which input and output modalities the model handles | -| `capabilities` | declared capabilities, e.g. `image_to_video` | -| `all` | every section. `?details=true` is a synonym | - -Unknown values are ignored rather than rejected, so a typo returns a valid response with that section missing. - -## Filtering - -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. - -| Parameter | Keeps models that… | -| --- | --- | -| `id` | match this id **or carry it as an alias** | -| `type` | are served through this endpoint type | -| `tags` | carry this tag, e.g. `playground:video` | -| `modalities` | have it among input **or** output modalities | -| `input_modalities` | accept this input modality | -| `output_modalities` | produce this output modality | -| `capabilities` | declare this capability | - -Rules that apply to all of them: - -* **Several values, one parameter β€” OR.** `?capabilities=text_to_video,image_to_video` returns models that do either. -* **Several parameters β€” AND.** `?output_modalities=video&capabilities=audio_generation` returns models that do both. -* Values are **case-insensitive**, and may be given comma-separated (`?tags=a,b`) or repeated (`?tags=a&tags=b`). Both forms merge. -* An omitted parameter filters nothing. - -```bash -# every model that turns an image into video -curl 'https://api.aimlapi.com/v1/models?capabilities=image_to_video' - -# what one specific model costs β€” a few kilobytes instead of the whole catalogue -curl 'https://api.aimlapi.com/v1/models?id=deepgram/aura-2&include=pricing' -``` - -## Checking whether a model is still available - -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. - -```js -const res = await fetch('https://api.aimlapi.com/v1/models'); -const { data } = await res.json(); - -const byName = new Map(); -for (const model of data) { - byName.set(model.id, model.id); - for (const alias of model.aliases ?? []) byName.set(alias, model.id); -} - -const canonical = byName.get(myModelId); // undefined β‡’ genuinely unavailable -``` - -The same map de-duplicates your list: two names resolving to one canonical id are one model, not two. - -## Reading prices - -With `?include=pricing`, each model carries a `pricing` block. Read `kind` first: - -| `kind` | What it means | -| --- | --- | -| `fixed` | one rate per unit, in `units[]` | -| `variants` | the rate depends on request parameters β€” `dimensions` names them, `variants[]` quotes a rate per combination | -| `variable` | the rate cannot be quoted ahead of the request | - -**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. - -```json -{ - "kind": "variants", - "dimensions": ["resolution"], - "variants": [ - { "when": { "resolution": "720p" }, "price": 0.39, "unit": "second", "per": 1 }, - { "when": { "resolution": "1080p" }, "price": 0.65, "unit": "second", "per": 1 } - ] -} -``` - -Here a 5-second 1080p generation costs `0.65 Γ— 5 = $3.25`. - -Prices are in USD and are what you are charged. - -## Caching - -Responses carry an `ETag`. Send it back as `If-None-Match` and you get `304 Not Modified` with an empty body when nothing changed: - -```bash -curl -I 'https://api.aimlapi.com/v1/models?include=pricing' -# etag: W/"1440a0-uH6NONsG/9An5njw3kqMcYY5k8w" - -curl -H 'If-None-Match: W/"1440a0-uH6NONsG/9An5njw3kqMcYY5k8w"' \ - 'https://api.aimlapi.com/v1/models?include=pricing' -# 304 -``` - -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. diff --git a/docs/service-endpoints/models-catalogue.json b/docs/service-endpoints/models-catalogue.json deleted file mode 100644 index 8277b856..00000000 --- a/docs/service-endpoints/models-catalogue.json +++ /dev/null @@ -1,223 +0,0 @@ -{ - "openapi": "3.0.0", - "info": { - "title": "AIML API", - "version": "1.0.0" - }, - "servers": [ - { - "url": "https://api.aimlapi.com" - } - ], - "paths": { - "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/v1/models": { - "get": { - "operationId": "_v1_models", - "summary": "List models", - "description": "Returns the model catalogue. By default each entry carries only its identity (`id`, `aliases`, `type`, `info`, `tags`); pricing, modalities and capabilities are opt-in through `include`.", - "parameters": [ - { - "name": "include", - "in": "query", - "required": false, - "description": "Comma-separated sections to attach: `pricing`, `modalities`, `capabilities`. `all` (or `details`) attaches every section. Unknown values are ignored rather than rejected.", - "schema": { - "type": "string", - "example": "pricing" - } - }, - { - "name": "details", - "in": "query", - "required": false, - "description": "Shorthand for `include=all`. Accepts `true` or `1`.", - "schema": { - "type": "string", - "example": "true" - } - }, - { - "name": "id", - "in": "query", - "required": false, - "description": "Keep only models matching these ids. Matches the canonical `id` **and** every entry in `aliases`, so a legacy name resolves to the model that serves it today.", - "schema": { - "type": "string", - "example": "gpt-5,aura-2-helena-en" - } - }, - { - "name": "type", - "in": "query", - "required": false, - "description": "Keep only models served through this endpoint type.", - "schema": { - "type": "string", - "example": "openai/chat-completions" - } - }, - { - "name": "tags", - "in": "query", - "required": false, - "description": "Keep only models carrying these tags.", - "schema": { - "type": "string", - "example": "playground:video" - } - }, - { - "name": "modalities", - "in": "query", - "required": false, - "description": "Keep only models whose input **or** output modalities include these values.", - "schema": { - "type": "string", - "example": "video" - } - }, - { - "name": "input_modalities", - "in": "query", - "required": false, - "description": "Keep only models that accept these input modalities.", - "schema": { - "type": "string", - "example": "image" - } - }, - { - "name": "output_modalities", - "in": "query", - "required": false, - "description": "Keep only models that produce these output modalities.", - "schema": { - "type": "string", - "example": "video" - } - }, - { - "name": "capabilities", - "in": "query", - "required": false, - "description": "Keep only models declaring these capabilities, e.g. `image_to_video`, `text_to_video`, `audio_generation`.", - "schema": { - "type": "string", - "example": "image_to_video" - } - } - ], - "responses": { - "200": { - "description": "The catalogue.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "object": { - "type": "string", - "example": "list" - }, - "data": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Canonical model id. Stable, provider-independent, and the value to store on your side.", - "example": "deepgram/aura-2" - }, - "aliases": { - "type": "array", - "description": "Every other name this model answers to. All of them keep working on input, forever.", - "items": { - "type": "string" - }, - "example": ["aura-2", "aura-2-helena-en"] - }, - "type": { - "type": "string", - "description": "The endpoint this entry is callable through.", - "example": "internal/text-to-speech" - }, - "info": { - "type": "object", - "description": "Display metadata: name, developer, description, context length, links." - }, - "tags": { - "type": "array", - "items": { - "type": "string" - }, - "example": ["playground:tts"] - }, - "pricing": { - "type": "object", - "description": "Present only with `include=pricing`. See the page body for how to read it.", - "properties": { - "currency": { - "type": "string", - "example": "USD" - }, - "kind": { - "type": "string", - "description": "`fixed` β€” one rate per unit. `variants` β€” the rate depends on request parameters, listed in `variants`. `variable` β€” the rate cannot be quoted up front.", - "example": "fixed" - }, - "units": { - "type": "array", - "description": "Rate lines. `price` is the charge for `per` units; `per` differs by unit, so never compare `price` across models without it. `price: null` means this line is request-dependent.", - "items": { - "type": "object" - } - }, - "thresholds": { - "type": "array", - "description": "Price bands that kick in above a request size.", - "items": { - "type": "object" - } - }, - "dimensions": { - "type": "array", - "description": "Request parameters the rate depends on.", - "items": { - "type": "string" - }, - "example": ["resolution"] - }, - "variants": { - "type": "array", - "description": "One quoted rate per combination of `dimensions`.", - "items": { - "type": "object" - } - } - } - }, - "modalities": { - "type": "object", - "description": "Present only with `include=modalities`." - }, - "capabilities": { - "type": "array", - "description": "Present only with `include=capabilities`.", - "items": { - "type": "string" - } - } - } - } - } - } - } - } - } - } - } - } - } - } -}