{"openapi":"3.0.0","info":{"description":"AIML API multi-model AI gateway — hundreds of AI models through one OpenAI-compatible endpoint; static Bearer key.","version":null},"servers":[{"description":"AIML API multi-model AI gateway — hundreds of AI models through one OpenAI-compatible endpoint; static Bearer key.","url":"https://api.apirails.com/aimlapi"}],"paths":{"/v1/chat/completions":{"post":{"tags":["Chat"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/quickstart/simple-model","api_endpoint":"https://api.aimlapi.com/v1/chat/completions"},"summary":"Create chat completion","description":"Given a list of messages comprising a conversation, the model returns a completion.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"max_tokens":{"type":"number","description":"Maximum number of tokens to generate before stopping."},"messages":{"type":"array","description":"The messages that make up the conversation so far.","required":true,"items":{"type":"object","properties":{"content":{"type":"string","description":"Content of the message.","required":true},"role":{"type":"string","description":"Role of the message sender.","required":true,"enum":["system","user","assistant"]}}}},"model":{"type":"string","description":"Model id to call, in source/alias form (for example google/gemma-3-4b-it, openai/gpt-5, anthropic/claude-sonnet-5).","required":true},"stream":{"type":"boolean","description":"Enable streaming mode: the model delivers responses as they are generated.","enum":[true,false]},"temperature":{"type":"number","description":"Amount of randomness injected into the generation."}}},"example":{"max_tokens":512,"messages":[{"content":"Tell me about San Francisco","role":"user"}],"model":"google/gemma-3-4b-it","stream":"","temperature":0.7}}}}}},"/v1/embeddings":{"post":{"tags":["Embeddings"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/embedding-models","api_endpoint":"https://api.aimlapi.com/v1/embeddings"},"summary":"Create embeddings","description":"Creates an embedding vector representing the input text.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"encoding_format":{"type":"string","description":"The format to return the embeddings in.","enum":["float","base64"]},"input":{"type":"string","description":"Input text to embed. Array input is also accepted by the API for batching multiple strings in one request.","required":true},"model":{"type":"string","description":"Id of the embedding model to use.","required":true}}},"example":{"encoding_format":"float","input":"Your text string goes here","model":"text-embedding-3-small"}}}}}},"/v1/images/generations":{"post":{"tags":["Images"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/image-models","api_endpoint":"https://api.aimlapi.com/v1/images/generations"},"summary":"Generate image","description":"Generates an image from a text prompt using the selected image model.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"model":{"type":"string","description":"Id of the image model to use.","required":true},"n":{"type":"number","description":"Number of iterations the model takes to shape the image."},"prompt":{"type":"string","description":"A text description of the desired image.","required":true},"size":{"type":"string","description":"Resolution of the resulting image. Flux models: min 64x64 (flux/schnell) or 256x256 (flux-pro), max 1536x1536/1440x1440, default 1024x768; both dimensions must be multiples of 32."}}},"example":{"model":"flux/schnell","n":1,"prompt":"A classroom of young robots","size":"1024x768"}}}}}},"/v1/models":{"get":{"tags":["Models"],"parameters":[{"name":"type","in":"query","description":"Keep models served through this endpoint type, for example openai/chat-completions.","required":false,"schema":{"type":"string","example":""}},{"name":"capabilities","in":"query","description":"Keep models declaring this capability, for example image_to_video.","required":false,"schema":{"type":"string","example":""}},{"name":"details","in":"query","description":"Shorthand for include=all.","required":false,"schema":{"type":"string","example":"","items":{"type":"string","enum":["true","1"]}}},{"name":"id","in":"query","description":"Keep models matching this id, or carrying it as an alias. Comma-separated or repeated values are combined with OR.","required":false,"schema":{"type":"string","example":""}},{"name":"include","in":"query","description":"Attach optional sections to each model: pricing, modalities, capabilities, or all for every section. Comma-separated and repeated values are both accepted.","required":false,"schema":{"type":"string","example":""}},{"name":"input_modalities","in":"query","description":"Keep models accepting this input modality.","required":false,"schema":{"type":"string","example":""}},{"name":"modalities","in":"query","description":"Keep models with this modality among either their input or output modalities.","required":false,"schema":{"type":"string","example":""}},{"name":"output_modalities","in":"query","description":"Keep models producing this output modality.","required":false,"schema":{"type":"string","example":""}},{"name":"tags","in":"query","description":"Keep models carrying this tag, for example playground:video.","required":false,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/complete-model-list","api_endpoint":"https://api.aimlapi.com/v1/models"},"summary":"List models","description":"Lists every model available on the AIML API, hundreds of AI models through one unified catalog.","security":[{"bearerAuth":[]}]}},"/v1/models/deprecations":{"get":{"tags":["Models"],"parameters":[{"name":"since","in":"query","description":"Keep only entries whose deprecated_at or shutdown_at falls on or after this date. Plain YYYY-MM-DD, no time part.","required":false,"schema":{"type":"string","example":""}},{"name":"status","in":"query","description":"Keep only entries in these states: deprecated, superseded or withdrawn. Values are case-insensitive and may be comma-separated or repeated.","required":false,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/model-deprecations","api_endpoint":"https://api.aimlapi.com/v1/models/deprecations"},"summary":"List model deprecations","description":"Lists deprecated, superseded and withdrawn models with their dates.","security":[{"bearerAuth":[]}]}},"/models/metrics":{"get":{"tags":["Models"],"parameters":[{"name":"aliases","in":"query","description":"Keep only these models. Repeat the parameter once per model (?aliases=openai/gpt-5&aliases=google/veo-3), up to 100 values, matched exactly. Omit to get every measured model.","required":false,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/model-metrics","api_endpoint":"https://api.aimlapi.com/models/metrics"},"summary":"Get model performance metrics","description":"Reports how fast models are responding right now: ttft_ms, tps and duration_ms as p50/p75/p90/p99 over a short sliding window, per model. No API key required.","security":[{"bearerAuth":[]}]}},"/v1/batches":{"post":{"tags":["Batch"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/capabilities/batch-processing","api_endpoint":"https://api.aimlapi.com/v1/batches"},"summary":"Create batch","description":"Submits a batch of model requests for asynchronous processing.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"requests":{"type":"array","description":"List of requests to process in the batch.","required":true,"items":{"type":"object","properties":{"params":{"type":"object","description":"Parameters passed to the model for this request."},"custom_id":{"type":"string","description":"A unique identifier for this request within the batch."}}}}}},"example":{"requests":[{"params":{"max_tokens":1024,"messages":[{"content":"Hello","role":"user"}],"model":"anthropic/claude-sonnet-5"},"custom_id":"req-1"}]}}}}},"get":{"tags":["Batch"],"parameters":[{"name":"batch_id","in":"query","description":"The id of the batch to retrieve its status and results.","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/capabilities/batch-processing","api_endpoint":"https://api.aimlapi.com/v1/batches"},"summary":"Get batch status and results","description":"Retrieves the status and results of a batch by id.","security":[{"bearerAuth":[]}]}},"/v1/batches/cancel/{batch_id}":{"post":{"tags":["Batch"],"parameters":[{"name":"batch_id","in":"path","description":"The id of the batch to cancel.","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/capabilities/batch-processing","api_endpoint":"https://api.aimlapi.com/v1/batches/cancel/{batch_id}"},"summary":"Cancel batch","description":"Cancels a queued or running batch.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{}},"example":{}}}}}},"/v1/keys":{"get":{"tags":["API Keys"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/api-key-management","api_endpoint":"https://api.aimlapi.com/v1/keys"},"summary":"List API keys","description":"Returns all API keys for your account, including each key's settings and metadata. Requires a management key.","security":[{"bearerAuth":[]}]},"post":{"tags":["API Keys"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/api-key-management","api_endpoint":"https://api.aimlapi.com/v1/keys"},"summary":"Create API key","description":"Creates a new API key. The full key value is returned only at creation time. Requires a management key.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"limit":{"type":"object","description":"Optional spending limit configuration.","properties":{"retention":{"type":"string","description":"Limit period.","enum":["no_reset","day","week","month"]},"threshold":{"type":"number","description":"Spending limit threshold for the selected period, in USD."}}},"name":{"type":"string","description":"Optional human-readable name of the API key."},"scopes":{"type":"array","description":"List of model access scopes assigned to the key. Defines which categories of models can be called using this API key.","enum":["model:chat","model:responses","model:image","model:audio","model:video","model:embeddings","model:speech","model:ocr"],"items":{"type":"string"}}}},"example":{"limit":{},"name":"production","scopes":["model:chat","model:embeddings"]}}}}}},"/v1/key":{"get":{"tags":["API Keys"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/api-key-management","api_endpoint":"https://api.aimlapi.com/v1/key"},"summary":"Get latest used API key","description":"Retrieves parameters of the most recently used API key.","security":[{"bearerAuth":[]}]}},"/v1/keys/{prefix}":{"patch":{"tags":["API Keys"],"parameters":[{"name":"prefix","in":"path","description":"Prefix of the API key to update: the first 8 characters of your API key, visible in the dashboard.","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/api-key-management","api_endpoint":"https://api.aimlapi.com/v1/keys/{prefix}"},"summary":"Update API key","description":"Updates an API key's name, disabled flag, spending limit or scopes. Requires a management key.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"disabled":{"type":"boolean","description":"Enable or disable the API key.","enum":[true,false]},"limit":{"type":"object","description":"Optional spending limit configuration.","properties":{"retention":{"type":"string","description":"Limit period.","enum":["no_reset","day","week","month"]},"threshold":{"type":"number","description":"Spending limit threshold for the selected period, in USD."}}},"name":{"type":"string","description":"Optional human-readable name of the API key."},"scopes":{"type":"array","description":"List of model access scopes assigned to the key.","enum":["model:chat","model:responses","model:image","model:audio","model:video","model:embeddings","model:speech","model:ocr"],"items":{"type":"string"}}}},"example":{"disabled":"","limit":{},"name":"production","scopes":["model:chat"]}}}}},"delete":{"tags":["API Keys"],"parameters":[{"name":"prefix","in":"path","description":"Prefix of the API key to delete: the first 8 characters of your API key, visible in the dashboard.","required":true,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/api-key-management","api_endpoint":"https://api.aimlapi.com/v1/keys/{prefix}"},"summary":"Delete API key","description":"Deletes an API key by prefix. Requires a management key.","security":[{"bearerAuth":[]}],"requestBody":{"description":"","required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{}},"example":{}}}}}},"/v2/billing":{"get":{"tags":["Billing"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/account-balance","api_endpoint":"https://api.aimlapi.com/v2/billing"},"summary":"Get balance info","description":"Returns the current balance in USD for the authenticated API key.","security":[{"bearerAuth":[]}]}},"/v2/billing/detail":{"get":{"tags":["Billing"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/account-balance","api_endpoint":"https://api.aimlapi.com/v2/billing/detail"},"summary":"Get detailed billing info","description":"Returns detailed billing info: user id, email, current balance and auto top-up settings.","security":[{"bearerAuth":[]}]}},"/v2/billing/transactions":{"get":{"tags":["Billing"],"parameters":[{"name":"type","in":"query","description":"Keep only entries of this kind.","required":false,"schema":{"type":"string","example":"","items":{"type":"string","enum":["PAYMENT","BONUS","REFUND","ADJUSTMENT","MODEL_USAGE","CREDITS_EXPIRED","INIT"]}}},{"name":"cursor","in":"query","description":"Position to continue from, taken verbatim from the previous response's pagination.next_cursor.","required":false,"schema":{"type":"string","example":""}},{"name":"direction","in":"query","description":"Keep only money coming in (TOPUP) or money going out (CHARGE).","required":false,"schema":{"type":"string","example":"","items":{"type":"string","enum":["TOPUP","CHARGE"]}}},{"name":"from","in":"query","description":"Only return entries created at or after this moment, ISO-8601 with an offset.","required":false,"schema":{"type":"string","example":""}},{"name":"limit","in":"query","description":"Entries per page, 1-100.","required":false,"schema":{"type":"number","example":""}},{"name":"to","in":"query","description":"Only return entries created before this moment, ISO-8601 with an offset. Must be later than from.","required":false,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/account-balance","api_endpoint":"https://api.aimlapi.com/v2/billing/transactions"},"summary":"Get account transactions","description":"Returns one entry per balance movement, newest first.","security":[{"bearerAuth":[]}]}},"/v1/billing/balance":{"get":{"tags":["Billing"],"parameters":[],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/account-balance","api_endpoint":"https://api.aimlapi.com/v1/billing/balance"},"summary":"Get account balance info (legacy)","description":"Legacy balance endpoint: total credits associated with the provided API key, low-balance flag and plan status.","security":[{"bearerAuth":[]}]}},"/v2/usage":{"get":{"tags":["Usage"],"parameters":[{"name":"end","in":"query","description":"Window end, ISO-8601. Must not be earlier than start, and the window must not exceed 92 days.","required":false,"schema":{"type":"string","example":""}},{"name":"key_prefix","in":"query","description":"Prefix of the key to report on. Omit it to get the spend of the key you are authenticating with. Reporting on a different key requires a management key.","required":false,"schema":{"type":"string","example":""}},{"name":"period","in":"query","description":"Relative window: a positive integer followed by h or d, for example 24h or 7d. Provide either period or both start and end, never both.","required":false,"schema":{"type":"string","example":""}},{"name":"start","in":"query","description":"Window start, ISO-8601. A value without a UTC offset is read as UTC. Must be used together with end.","required":false,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/api-key-usage","api_endpoint":"https://api.aimlapi.com/v2/usage"},"summary":"Get API key usage","description":"Returns the spend of the API key over the requested window (flat total).","security":[{"bearerAuth":[]}]}},"/v2/usage/detail":{"get":{"tags":["Usage"],"parameters":[{"name":"end","in":"query","description":"Window end, ISO-8601. Must not be earlier than start, and the window must not exceed 92 days.","required":false,"schema":{"type":"string","example":""}},{"name":"group_by","in":"query","description":"Add a groups array to the response, grouped by day, by model, or by both.","required":false,"schema":{"type":"string","example":"","items":{"type":"string","enum":["day","model","day,model"]}}},{"name":"key_prefix","in":"query","description":"Prefix of the key to report on. Omit it to get the spend of the key you are authenticating with. Reporting on a different key requires a management key.","required":false,"schema":{"type":"string","example":""}},{"name":"period","in":"query","description":"Relative window: a positive integer followed by h or d, for example 24h or 7d. Provide either period or both start and end, never both.","required":false,"schema":{"type":"string","example":""}},{"name":"start","in":"query","description":"Window start, ISO-8601. A value without a UTC offset is read as UTC. Must be used together with end.","required":false,"schema":{"type":"string","example":""}},{"name":"tz","in":"query","description":"Time zone that defines the day boundary for group_by=day. Must be a canonical IANA zone name matched exactly.","required":false,"schema":{"type":"string","example":""}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/api-key-usage","api_endpoint":"https://api.aimlapi.com/v2/usage/detail"},"summary":"Get detailed API key usage","description":"Returns detailed per-model usage of the API key over the requested window, optionally grouped.","security":[{"bearerAuth":[]}]}},"/v2/logs":{"get":{"tags":["Usage Logs"],"parameters":[{"name":"end","in":"query","description":"Window end, ISO-8601. Must not be earlier than start, and the window must not exceed 92 days.","required":false,"schema":{"type":"string","example":""}},{"name":"key_prefix","in":"query","description":"Prefix of the key to report on. Omit it to list the requests made with the key you are authenticating with.","required":false,"schema":{"type":"string","example":""}},{"name":"limit","in":"query","description":"Rows per page, 1-100.","required":false,"schema":{"type":"number","example":""}},{"name":"model","in":"query","description":"Keep only requests made to this model. Accepts source/alias (openai/gpt-5) or a bare alias (gpt-5), matched exactly.","required":false,"schema":{"type":"string","example":""}},{"name":"offset","in":"query","description":"Rows to skip before the page starts.","required":false,"schema":{"type":"number","example":""}},{"name":"period","in":"query","description":"Relative window: a positive integer followed by h or d, for example 24h or 7d. Provide either period or both start and end, never both.","required":false,"schema":{"type":"string","example":""}},{"name":"start","in":"query","description":"Window start, ISO-8601. A value without a UTC offset is read as UTC. Must be used together with end.","required":false,"schema":{"type":"string","example":""}},{"name":"status","in":"query","description":"Keep only requests with this outcome. Repeat the parameter to accept both.","required":false,"schema":{"type":"string","example":"","items":{"type":"string","enum":["succeeded","failed"]}}}],"responses":{"401":{"description":"Bearer token required (Authorization header)","content":{"application/json":{}}}},"externalDocs":{"api_ref":"https://docs.aimlapi.com/api-references/service-endpoints/usage-logs","api_endpoint":"https://api.aimlapi.com/v2/logs"},"summary":"Get usage logs","description":"Lists the inference requests made with the key, newest first, filterable by model and outcome.","security":[{"bearerAuth":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"security":[{"bearerAuth":[]}]}