aimldocs

OpenAI-compatible

OpenAI Chat Completions wire format; the OpenAI SDKs work unchanged

POST
/v1/chat/completions
AuthorizationBearer <token>

In: header

Header Parameters

aiml-version?string

API version (YYYY-MM-DD); defaults to the key's pinned version

Formatdate
x-aiml-debug?"1"

returns the route trace in x-aiml-route-trace

Value in

  • "1"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

OpenAI Chat Completions request; extra aiml object accepted (route, metadata, compat, provider_options)

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/v1/chat/completions" \  -H "Content-Type: application/json" \  -d '{    "model": "openai/gpt-5-mini",    "messages": [      {        "role": "user",        "content": "hi"      }    ],    "stream": false,    "aiml": {      "route": {        "sort": "price"      },      "metadata": {        "app": "chatbot"      }    }  }'
{  "id": "chatcmpl-01J9ZK2K4Q7Q3M3QX1V0F1GATE",  "object": "chat.completion",  "created": 1789041540,  "model": "openai/gpt-5-mini",  "choices": [    {      "index": 0,      "message": {        "role": "assistant",        "content": "Hello! How can I help?"      },      "finish_reason": "stop"    }  ],  "usage": {    "prompt_tokens": 812,    "completion_tokens": 143,    "total_tokens": 955  },  "aiml": {    "request_id": "01J9ZK2K4Q7Q3M3QX1V0F1GATE",    "provider": "openai",    "endpoint_id": "ep_openai_gpt-5-mini_us",    "cost": {      "total_micro_usd": 489,      "lines": [        {          "kind": "input",          "units": 812,          "unit_price_nano": 250,          "micro_usd": 203        },        {          "kind": "output",          "units": 143,          "unit_price_nano": 2000,          "micro_usd": 286        }      ],      "price_version": "pv_01J9ZK2K4Q7Q3M3QX1V0F1PV01"    },    "warnings": []  }}
POST
/v1/audio/transcriptions
AuthorizationBearer <token>

In: header

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/v1/audio/transcriptions" \  -F file="string" \  -F model="string"
{  "text": "Thanks for calling. How can I help?",  "usage": {    "type": "duration",    "seconds": 4  },  "aiml": {    "request_id": "01J9ZK2K4Q7Q3M3QX1V0F1AUD1",    "resolved": {      "provider": "openai",      "endpoint_id": "ep_openai_whisper-1_us",      "region": "us"    },    "cost": {      "total_micro_usd": 400,      "lines": [        {          "kind": "audio_in",          "units": 4,          "unit_price_nano": 100000,          "micro_usd": 400        }      ]    }  }}
POST
/v1/audio/speech
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/v1/audio/speech" \  -H "Content-Type: application/json" \  -d '{    "model": "openai/tts-1",    "input": "Your order has shipped.",    "voice": "alloy",    "response_format": "mp3"  }'
"string"
GET
/v1/files
AuthorizationBearer <token>

In: header

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/files"
{  "object": "list",  "has_more": false,  "data": [    {      "id": "file-01J9ZK2K4Q7Q3M3QX1V0F1FIL1",      "object": "file",      "bytes": 1840,      "created_at": 1792400000,      "expires_at": 1794992000,      "filename": "requests.jsonl",      "purpose": "batch",      "status": "processed"    }  ]}
POST
/v1/files
AuthorizationBearer <token>

In: header

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/files" \  -F file="string" \  -F purpose="batch"
{  "id": "file-01J9ZK2K4Q7Q3M3QX1V0F1FIL1",  "object": "file",  "bytes": 1840,  "created_at": 1792400000,  "expires_at": 1794992000,  "filename": "requests.jsonl",  "purpose": "batch",  "status": "processed"}
GET
/v1/files/{id}
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/files/string"
{  "id": "file-01J9ZK2K4Q7Q3M3QX1V0F1FIL1",  "object": "file",  "bytes": 1840,  "created_at": 1792400000,  "expires_at": 1794992000,  "filename": "requests.jsonl",  "purpose": "batch",  "status": "processed"}
DELETE
/v1/files/{id}
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X DELETE "https://example.com/v1/files/string"
{  "id": "file-01J9ZK2K4Q7Q3M3QX1V0F1FIL1",  "object": "file",  "deleted": true}
GET
/v1/files/{id}/content
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/jsonl

application/json

curl -X GET "https://example.com/v1/files/string/content"
"string"
GET
/v1/batches
AuthorizationBearer <token>

In: header

Query Parameters

limit?integer
Rangevalue <= 100
Default20
after?string

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/batches"
{  "object": "list",  "data": [],  "has_more": false}
POST
/v1/batches
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/batches" \  -H "Content-Type: application/json" \  -d '{    "input_file_id": "file-01J9ZK2K4Q7Q3M3QX1V0F1FIL1",    "endpoint": "/v1/chat/completions",    "completion_window": "24h",    "metadata": {      "job": "nightly"    }  }'
{  "id": "batch_01J9ZK2K4Q7Q3M3QX1V0F1BAT1",  "object": "batch",  "endpoint": "/v1/chat/completions",  "errors": null,  "input_file_id": "file-01J9ZK2K4Q7Q3M3QX1V0F1FIL1",  "completion_window": "24h",  "status": "completed",  "output_file_id": "file-01J9ZK2K4Q7Q3M3QX1V0F1OUT1",  "error_file_id": null,  "created_at": 1792400000,  "in_progress_at": 1792400000,  "expires_at": 1792486400,  "finalizing_at": 1792400420,  "completed_at": 1792400421,  "failed_at": null,  "expired_at": null,  "cancelling_at": null,  "cancelled_at": null,  "request_counts": {    "total": 3,    "completed": 3,    "failed": 0  },  "metadata": {    "job": "nightly"  },  "cost_micro_usd": 2610}
GET
/v1/batches/{id}
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/batches/string"
{  "id": "batch_01J9ZK2K4Q7Q3M3QX1V0F1BAT1",  "object": "batch",  "endpoint": "/v1/chat/completions",  "errors": null,  "input_file_id": "file-01J9ZK2K4Q7Q3M3QX1V0F1FIL1",  "completion_window": "24h",  "status": "completed",  "output_file_id": "file-01J9ZK2K4Q7Q3M3QX1V0F1OUT1",  "error_file_id": null,  "created_at": 1792400000,  "in_progress_at": 1792400000,  "expires_at": 1792486400,  "finalizing_at": 1792400420,  "completed_at": 1792400421,  "failed_at": null,  "expired_at": null,  "cancelling_at": null,  "cancelled_at": null,  "request_counts": {    "total": 3,    "completed": 3,    "failed": 0  },  "metadata": {    "job": "nightly"  },  "cost_micro_usd": 2610}
POST
/v1/batches/{id}/cancel
AuthorizationBearer <token>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X POST "https://example.com/v1/batches/string/cancel"
{  "id": "batch_01J9ZK2K4Q7Q3M3QX1V0F1BAT1",  "object": "batch",  "endpoint": "/v1/chat/completions",  "errors": null,  "input_file_id": "file-01J9ZK2K4Q7Q3M3QX1V0F1FIL1",  "completion_window": "24h",  "status": "completed",  "output_file_id": "file-01J9ZK2K4Q7Q3M3QX1V0F1OUT1",  "error_file_id": null,  "created_at": 1792400000,  "in_progress_at": 1792400000,  "expires_at": 1792486400,  "finalizing_at": 1792400420,  "completed_at": 1792400421,  "failed_at": null,  "expired_at": null,  "cancelling_at": null,  "cancelled_at": null,  "request_counts": {    "total": 3,    "completed": 3,    "failed": 0  },  "metadata": {    "job": "nightly"  },  "cost_micro_usd": 2610}
POST
/v1/embeddings
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/v1/embeddings" \  -H "Content-Type: application/json" \  -d '{    "model": "openai/text-embedding-3-small",    "input": [      "the prepaid ledger settles once per request"    ],    "dimensions": 512  }'
{  "object": "list",  "model": "openai/text-embedding-3-small",  "data": [    {      "object": "embedding",      "index": 0,      "embedding": [        0.0123,        -0.0456      ]    }  ],  "usage": {    "prompt_tokens": 9,    "total_tokens": 9  }}
POST
/v1/completions
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/completions" \  -H "Content-Type: application/json" \  -d '{    "model": "openai/gpt-5-mini",    "prompt": "Hello"  }'
{  "id": "cmpl-01J9ZK2K4Q7Q3M3QX1V0F1GATE",  "object": "text_completion",  "created": 1789041540,  "model": "openai/gpt-5-mini",  "choices": [    {      "index": 0,      "text": " world",      "finish_reason": "stop"    }  ],  "usage": {    "prompt_tokens": 1,    "completion_tokens": 1,    "total_tokens": 2  }}
POST
/v1/responses
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/responses" \  -H "Content-Type: application/json" \  -d '{    "model": "openai/gpt-5-mini",    "input": "hi"  }'
{  "id": "resp_01J9ZK2K4Q7Q3M3QX1V0F1GATE",  "object": "response",  "model": "openai/gpt-5-mini",  "output": [    {      "type": "message",      "role": "assistant",      "content": [        {          "type": "output_text",          "text": "Hello! How can I help?"        }      ]    }  ],  "usage": {    "input_tokens": 812,    "output_tokens": 143  }}