# Chat Completions

Create chat completions using various LLM models. Compatible with the OpenAI chat completions API format.

## Create chat completion

> Creates a chat completion for the provided messages using the specified model. This endpoint is compatible with the OpenAI chat completions API format.\
> \
> The request is validated and then routed to the appropriate LLM provider. Your account balance is checked before processing.<br>

````json
{"openapi":"3.0.3","info":{"title":"Consumption API","version":"1.0.0"},"tags":[{"name":"Chat Completions","description":"Create chat completions using various LLM models. Compatible with the OpenAI chat completions API format.\n"}],"servers":[{"url":"https://api.thegrid.ai/v1","description":"Grid Consumption API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication using your API key.\n\nInclude your API key in the Authorization header:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\nGenerate API keys from your [Grid Dashboard](https://app.thegrid.ai/profile/api-keys).\n"}},"schemas":{"ChatCompletionsRequest":{"title":"ChatCompletionsRequest","type":"object","required":["messages"],"properties":{"model":{"type":"string"},"messages":{"type":"array","minItems":1,"items":{"oneOf":[{"$ref":"#/components/schemas/ChatCompletionSystemMessageParam"},{"$ref":"#/components/schemas/ChatCompletionDeveloperMessageParam"},{"$ref":"#/components/schemas/ChatCompletionUserMessageParam"},{"$ref":"#/components/schemas/ChatCompletionAssistantMessageParam"},{"$ref":"#/components/schemas/ChatCompletionToolMessageParam"}]}},"max_tokens":{"type":"integer","minimum":1,"nullable":true,"deprecated":true},"max_completion_tokens":{"type":"integer","minimum":1,"nullable":true},"temperature":{"type":"number","minimum":0,"maximum":2,"default":1,"nullable":true},"top_p":{"type":"number","minimum":0,"maximum":1,"default":1,"nullable":true},"n":{"type":"integer","minimum":1,"maximum":128,"default":1,"nullable":true},"stream":{"type":"boolean","default":false,"nullable":true},"stream_options":{"type":"object","nullable":true,"properties":{"include_usage":{"type":"boolean"},"include_obfuscation":{"type":"boolean"}}},"stop":{"nullable":true,"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"maxItems":4}]},"logprobs":{"type":"boolean","default":false,"nullable":true},"top_logprobs":{"type":"integer","minimum":0,"maximum":20,"nullable":true},"response_format":{"nullable":true,"oneOf":[{"$ref":"#/components/schemas/ResponseFormatText"},{"$ref":"#/components/schemas/ResponseFormatJSONObject"},{"$ref":"#/components/schemas/ResponseFormatJSONSchema"}]},"tools":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/ChatCompletionTool"}},"tool_choice":{"nullable":true,"oneOf":[{"type":"string","enum":["none","auto","required"]},{"$ref":"#/components/schemas/ChatCompletionNamedToolChoice"}]},"parallel_tool_calls":{"type":"boolean","default":true},"frequency_penalty":{"type":"number","minimum":-2,"maximum":2,"default":0,"nullable":true},"presence_penalty":{"type":"number","minimum":-2,"maximum":2,"default":0,"nullable":true},"logit_bias":{"type":"object","additionalProperties":{"type":"integer","minimum":-100,"maximum":100},"nullable":true},"seed":{"type":"integer","nullable":true},"service_tier":{"type":"string","enum":["auto","default","flex","scale","priority"],"nullable":true},"reasoning_effort":{"type":"string","enum":["none","minimal","low","medium","high","xhigh"],"nullable":true},"modalities":{"type":"array","nullable":true,"items":{"type":"string","enum":["text","audio"]}},"audio":{"type":"object","nullable":true,"properties":{"voice":{"oneOf":[{"type":"string"},{"type":"string","enum":["alloy","ash","ballad","coral","echo","sage","shimmer","verse","marin","cedar"]},{"type":"object","properties":{"id":{"type":"string"}}}]},"format":{"type":"string","enum":["wav","aac","mp3","flac","opus","pcm16"]}}},"prediction":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["content"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/ChatCompletionContentPartText"}}]}}},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":512},"nullable":true},"store":{"type":"boolean","nullable":true},"verbosity":{"type":"string","enum":["low","medium","high"],"nullable":true},"web_search_options":{"type":"object","nullable":true,"properties":{"search_context_size":{"type":"string","enum":["low","medium","high"],"default":"medium"},"user_location":{"type":"object","properties":{"type":{"type":"string","enum":["approximate"]},"approximate":{"type":"object","properties":{"city":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"timezone":{"type":"string"}}}}}}},"prompt_cache_key":{"type":"string","nullable":true},"prompt_cache_retention":{"type":"string","enum":["in-memory","24h"],"nullable":true},"safety_identifier":{"type":"string","nullable":true},"route":{"type":"string","enum":["fallback"]},"provider":{"type":"object"},"user":{"type":"string","deprecated":true}}},"ChatCompletionSystemMessageParam":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["system"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/ChatCompletionContentPartText"}}]},"name":{"type":"string"}}},"ChatCompletionContentPartText":{"type":"object","required":["type","text"],"properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string"}}},"ChatCompletionDeveloperMessageParam":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["developer"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/ChatCompletionContentPartText"}}]},"name":{"type":"string"}}},"ChatCompletionUserMessageParam":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/ChatCompletionContentPartText"},{"$ref":"#/components/schemas/ChatCompletionContentPartImage"},{"$ref":"#/components/schemas/ChatCompletionContentPartInputAudio"}]}}]},"name":{"type":"string"}}},"ChatCompletionContentPartImage":{"type":"object","required":["type","image_url"],"properties":{"type":{"type":"string","enum":["image_url"]},"image_url":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"detail":{"type":"string","enum":["auto","low","high"],"default":"auto"}}}}},"ChatCompletionContentPartInputAudio":{"type":"object","required":["type","input_audio"],"properties":{"type":{"type":"string","enum":["input_audio"]},"input_audio":{"type":"object","required":["data","format"],"properties":{"data":{"type":"string"},"format":{"type":"string","enum":["wav","mp3"]}}}}},"ChatCompletionAssistantMessageParam":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["assistant"]},"content":{"nullable":true,"oneOf":[{"type":"string"},{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/ChatCompletionContentPartText"},{"$ref":"#/components/schemas/ChatCompletionContentPartRefusal"}]}}]},"name":{"type":"string"},"tool_calls":{"type":"array","items":{"$ref":"#/components/schemas/ChatCompletionMessageToolCall"}},"audio":{"type":"object","nullable":true,"properties":{"id":{"type":"string"}}}}},"ChatCompletionContentPartRefusal":{"type":"object","required":["type","refusal"],"properties":{"type":{"type":"string","enum":["refusal"]},"refusal":{"type":"string"}}},"ChatCompletionMessageToolCall":{"type":"object","required":["id","type","function"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["function"]},"function":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string"},"arguments":{"type":"string"}}}}},"ChatCompletionToolMessageParam":{"type":"object","required":["role","content","tool_call_id"],"properties":{"role":{"type":"string","enum":["tool"]},"content":{"oneOf":[{"type":"string"},{"type":"array","items":{"$ref":"#/components/schemas/ChatCompletionContentPartText"}}]},"tool_call_id":{"type":"string"}}},"ResponseFormatText":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["text"]}}},"ResponseFormatJSONObject":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["json_object"]}}},"ResponseFormatJSONSchema":{"type":"object","required":["type","json_schema"],"properties":{"type":{"type":"string","enum":["json_schema"]},"json_schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":64},"description":{"type":"string"},"schema":{"type":"object"},"strict":{"type":"boolean","nullable":true}}}}},"ChatCompletionTool":{"type":"object","required":["type","function"],"properties":{"type":{"type":"string","enum":["function"]},"function":{"$ref":"#/components/schemas/FunctionDefinition"}}},"FunctionDefinition":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":64},"description":{"type":"string"},"parameters":{"type":"object"},"strict":{"type":"boolean","nullable":true}}},"ChatCompletionNamedToolChoice":{"type":"object","required":["type","function"],"properties":{"type":{"type":"string","enum":["function"]},"function":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}},"ChatCompletionResponse":{"title":"ChatCompletionResponse","type":"object","required":["id","object","created","model","choices"],"properties":{"id":{"type":"string"},"object":{"type":"string","enum":["chat.completion"]},"created":{"type":"integer"},"model":{"type":"string"},"system_fingerprint":{"type":"string","nullable":true},"service_tier":{"type":"string","enum":["auto","default","flex","scale","priority"],"nullable":true},"choices":{"type":"array","items":{"$ref":"#/components/schemas/ChatCompletionChoice"}},"usage":{"$ref":"#/components/schemas/CompletionUsage"}}},"ChatCompletionChoice":{"type":"object","required":["index","message","finish_reason"],"properties":{"index":{"type":"integer"},"message":{"$ref":"#/components/schemas/ChatCompletionResponseMessage"},"logprobs":{"type":"object","nullable":true,"properties":{"content":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"}},"refusal":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/ChatCompletionTokenLogprob"}}}},"finish_reason":{"type":"string","enum":["stop","length","tool_calls","content_filter","function_call"],"nullable":true}}},"ChatCompletionResponseMessage":{"type":"object","required":["role"],"properties":{"role":{"type":"string","enum":["assistant"]},"content":{"type":"string","nullable":true},"refusal":{"type":"string","nullable":true},"tool_calls":{"type":"array","items":{"$ref":"#/components/schemas/ChatCompletionMessageToolCall"}},"audio":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"expires_at":{"type":"integer"},"data":{"type":"string"},"transcript":{"type":"string"}}}}},"ChatCompletionTokenLogprob":{"type":"object","required":["token","logprob","bytes","top_logprobs"],"properties":{"token":{"type":"string"},"logprob":{"type":"number"},"bytes":{"type":"array","nullable":true,"items":{"type":"integer"}},"top_logprobs":{"type":"array","items":{"type":"object","required":["token","logprob","bytes"],"properties":{"token":{"type":"string"},"logprob":{"type":"number"},"bytes":{"type":"array","nullable":true,"items":{"type":"integer"}}}}}}},"CompletionUsage":{"type":"object","required":["prompt_tokens","completion_tokens","total_tokens"],"properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"prompt_tokens_details":{"type":"object","nullable":true,"properties":{"cached_tokens":{"type":"integer"},"audio_tokens":{"type":"integer"}}},"completion_tokens_details":{"type":"object","nullable":true,"properties":{"reasoning_tokens":{"type":"integer"},"audio_tokens":{"type":"integer"},"accepted_prediction_tokens":{"type":"integer"},"rejected_prediction_tokens":{"type":"integer"}}}}},"ErrorResponse":{"title":"ErrorResponse","description":"Error response returned when a request fails","type":"object","required":["errors"],"properties":{"errors":{"description":"Error details. Can be either:\n- An object with a `detail` field for general errors\n- An array of validation errors with `path`, `message`, and `value` fields\n","oneOf":[{"type":"object","required":["detail"],"properties":{"detail":{"type":"string","description":"Human-readable error message"}}},{"type":"array","description":"List of validation errors","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string","description":"The field path that caused the error"},"message":{"type":"string","description":"Description of the validation error"},"value":{"type":"string","description":"The invalid value that was provided"}}}}]}}},"BalanceError":{"title":"BalanceError","description":"Error response for balance-related issues (e.g., replenishment in progress)","type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","type"],"properties":{"code":{"type":"string","description":"Error code identifier"},"message":{"type":"string","description":"Human-readable error message"},"type":{"type":"string","description":"Error type classification"},"param":{"type":"string","nullable":true,"description":"The parameter that caused the error, if applicable"}}}}}}},"paths":{"/chat/completions":{"post":{"summary":"Create chat completion","description":"Creates a chat completion for the provided messages using the specified model. This endpoint is compatible with the OpenAI chat completions API format.\n\nThe request is validated and then routed to the appropriate LLM provider. Your account balance is checked before processing.\n","operationId":"createChatCompletion","tags":["Chat Completions"],"requestBody":{"description":"Chat completion request parameters","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionsRequest"}}}},"responses":{"200":{"description":"Chat completion response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionResponse"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Model not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service Unavailable - Balance replenishment in progress. Retry the request after a short delay.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceError"}}}}}}}}}
````