# OpenAI Chat API

`POST /v1/chat/completions`

Creates a model response from the conversation history. Streaming and non-streaming responses are both supported.

Compatible with the OpenAI Chat Completions API.

## Authorizations

Bearer authentication — send `Authorization: Bearer <token>`.

## Request Body (application/json) — required

```json
{
  "type": "object",
  "required": [
    "model",
    "messages"
  ],
  "properties": {
    "model": {
      "type": "string",
      "description": "Model ID",
      "example": "gpt-4"
    },
    "messages": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "role",
          "content"
        ],
        "properties": {
          "role": {
            "type": "string",
            "enum": [
              "system",
              "user",
              "assistant",
              "tool",
              "developer"
            ],
            "description": "Message role"
          },
          "content": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "text",
                        "image_url",
                        "input_audio",
                        "file",
                        "video_url"
                      ]
                    },
                    "text": {
                      "type": "string"
                    },
                    "image_url": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string",
                          "description": "Image URL or base64 data"
                        },
                        "detail": {
                          "type": "string",
                          "enum": [
                            "low",
                            "high",
                            "auto"
                          ]
                        }
                      }
                    },
                    "input_audio": {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "string",
                          "description": "Base64-encoded audio data"
                        },
                        "format": {
                          "type": "string",
                          "enum": [
                            "wav",
                            "mp3"
                          ]
                        }
                      }
                    },
                    "file": {
                      "type": "object",
                      "properties": {
                        "filename": {
                          "type": "string"
                        },
                        "file_data": {
                          "type": "string"
                        },
                        "file_id": {
                          "type": "string"
                        }
                      }
                    },
                    "video_url": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            ],
            "description": "Message content"
          },
          "name": {
            "type": "string",
            "description": "Sender name"
          },
          "tool_calls": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "example": "function"
                },
                "function": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "arguments": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "tool_call_id": {
            "type": "string",
            "description": "Tool call ID (for messages with the `tool` role)"
          },
          "reasoning_content": {
            "type": "string",
            "description": "Reasoning content"
          }
        }
      },
      "description": "Conversation messages"
    },
    "temperature": {
      "type": "number",
      "minimum": 0,
      "maximum": 2,
      "default": 1,
      "description": "Sampling temperature"
    },
    "top_p": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "default": 1,
      "description": "Nucleus sampling (top_p)"
    },
    "n": {
      "type": "integer",
      "minimum": 1,
      "default": 1,
      "description": "Number of completions to generate"
    },
    "stream": {
      "type": "boolean",
      "default": false,
      "description": "Whether to stream the response"
    },
    "stream_options": {
      "type": "object",
      "properties": {
        "include_usage": {
          "type": "boolean"
        }
      }
    },
    "stop": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ],
      "description": "Stop sequences"
    },
    "max_tokens": {
      "type": "integer",
      "description": "Maximum tokens to generate"
    },
    "max_completion_tokens": {
      "type": "integer",
      "description": "Maximum completion tokens"
    },
    "presence_penalty": {
      "type": "number",
      "minimum": -2,
      "maximum": 2,
      "default": 0
    },
    "frequency_penalty": {
      "type": "number",
      "minimum": -2,
      "maximum": 2,
      "default": 0
    },
    "logit_bias": {
      "type": "object",
      "additionalProperties": {
        "type": "number"
      },
      "properties": {}
    },
    "user": {
      "type": "string"
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "example": "function"
          },
          "function": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "parameters": {
                "type": "object",
                "description": "Parameter definition as a JSON Schema",
                "properties": {}
              }
            }
          }
        }
      }
    },
    "tool_choice": {
      "oneOf": [
        {
          "type": "string",
          "enum": [
            "none",
            "auto",
            "required"
          ]
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "function": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                }
              }
            }
          }
        }
      ]
    },
    "response_format": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "text",
            "json_object",
            "json_schema"
          ]
        },
        "json_schema": {
          "type": "object",
          "description": "JSON Schema definition",
          "properties": {}
        }
      }
    },
    "seed": {
      "type": "integer"
    },
    "reasoning_effort": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ],
      "description": "Reasoning effort (for reasoning-capable models)"
    },
    "modalities": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "text",
          "audio"
        ]
      }
    },
    "audio": {
      "type": "object",
      "properties": {
        "voice": {
          "type": "string"
        },
        "format": {
          "type": "string"
        }
      }
    }
  }
}
```

## Responses

### 200 — Response created

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "object": {
      "type": "string",
      "example": "chat.completion"
    },
    "created": {
      "type": "integer"
    },
    "model": {
      "type": "string"
    },
    "choices": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer"
          },
          "message": {
            "type": "object",
            "required": [
              "role",
              "content"
            ],
            "properties": {
              "role": {
                "type": "string",
                "enum": [
                  "system",
                  "user",
                  "assistant",
                  "tool",
                  "developer"
                ],
                "description": "Message role"
              },
              "content": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "text",
                            "image_url",
                            "input_audio",
                            "file",
                            "video_url"
                          ]
                        },
                        "text": {
                          "type": "string"
                        },
                        "image_url": {
                          "type": "object",
                          "properties": {
                            "url": {
                              "type": "string",
                              "description": "Image URL or base64 data"
                            },
                            "detail": {
                              "type": "string",
                              "enum": [
                                "low",
                                "high",
                                "auto"
                              ]
                            }
                          }
                        },
                        "input_audio": {
                          "type": "object",
                          "properties": {
                            "data": {
                              "type": "string",
                              "description": "Base64-encoded audio data"
                            },
                            "format": {
                              "type": "string",
                              "enum": [
                                "wav",
                                "mp3"
                              ]
                            }
                          }
                        },
                        "file": {
                          "type": "object",
                          "properties": {
                            "filename": {
                              "type": "string"
                            },
                            "file_data": {
                              "type": "string"
                            },
                            "file_id": {
                              "type": "string"
                            }
                          }
                        },
                        "video_url": {
                          "type": "object",
                          "properties": {
                            "url": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                ],
                "description": "Message content"
              },
              "name": {
                "type": "string",
                "description": "Sender name"
              },
              "tool_calls": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "example": "function"
                    },
                    "function": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "arguments": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              },
              "tool_call_id": {
                "type": "string",
                "description": "Tool call ID (for messages with the `tool` role)"
              },
              "reasoning_content": {
                "type": "string",
                "description": "Reasoning content"
              }
            }
          },
          "finish_reason": {
            "type": "string",
            "enum": [
              "stop",
              "length",
              "tool_calls",
              "content_filter"
            ]
          }
        }
      }
    },
    "usage": {
      "type": "object",
      "properties": {
        "prompt_tokens": {
          "type": "integer",
          "description": "Prompt tokens"
        },
        "completion_tokens": {
          "type": "integer",
          "description": "Completion tokens"
        },
        "total_tokens": {
          "type": "integer",
          "description": "Total tokens"
        },
        "prompt_tokens_details": {
          "type": "object",
          "properties": {
            "cached_tokens": {
              "type": "integer"
            },
            "text_tokens": {
              "type": "integer"
            },
            "audio_tokens": {
              "type": "integer"
            },
            "image_tokens": {
              "type": "integer"
            }
          }
        },
        "completion_tokens_details": {
          "type": "object",
          "properties": {
            "text_tokens": {
              "type": "integer"
            },
            "audio_tokens": {
              "type": "integer"
            },
            "reasoning_tokens": {
              "type": "integer"
            }
          }
        }
      }
    },
    "system_fingerprint": {
      "type": "string"
    }
  }
}
```

### 400 — Invalid request parameters

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "description": "Error message"
        },
        "type": {
          "type": "string",
          "description": "Error type"
        },
        "param": {
          "type": "string",
          "description": "Related parameter",
          "nullable": true
        },
        "code": {
          "type": "string",
          "description": "Error code",
          "nullable": true
        }
      }
    }
  }
}
```

### 429 — Rate limited

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "description": "Error message"
        },
        "type": {
          "type": "string",
          "description": "Error type"
        },
        "param": {
          "type": "string",
          "description": "Related parameter",
          "nullable": true
        },
        "code": {
          "type": "string",
          "description": "Error code",
          "nullable": true
        }
      }
    }
  }
}
```