> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hicap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> OpenAI-compatible REST API for accessing foundation models through Hicap

The Hicap API is a RESTful API compatible with the [OpenAI API specification](https://github.com/openai/openai-openapi). Use it from any environment that supports HTTP requests, or through OpenAI's official SDKs for [Python](https://github.com/openai/openai-python), [JavaScript/TypeScript](https://github.com/openai/openai-node), [Go](https://github.com/openai/openai-go), and more.

<Info>
  **Base URL:** `https://api.hicap.ai/v1`
</Info>

***

## Authentication

The Hicap API uses API keys for authentication. Create and manage your API keys in the [Hicap Platform ↗](https://platform.hicap.ai/).

<Warning>
  Your API key is a secret. Do not share it or expose it in client-side code (browsers, mobile apps). Load API keys from environment variables or a secrets manager on the server side.
</Warning>

Provide your key via one of these headers:

```bash theme={null}
# Bearer authentication (OpenAI SDK default)
Authorization: Bearer YOUR-HICAP-API-KEY

# api-key header (Azure-style, also supported)
api-key: YOUR-HICAP-API-KEY
```

### Example request

```bash theme={null}
curl https://api.hicap.ai/v1/chat/completions \
  -H "Authorization: Bearer $HICAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Hello, world"}]
  }'
```

***

## Endpoints

All endpoints follow the [OpenAI OpenAPI specification](https://github.com/openai/openai-openapi).

### Production

These endpoints are available on the production Hicap API (`api.hicap.ai`).

#### Models

| Endpoint                                                               | Method | Description                              |
| ---------------------------------------------------------------------- | ------ | ---------------------------------------- |
| [`/v1/models`](/api-reference/endpoints/openAI/lists-available-models) | `GET`  | List model IDs available to your API key |

#### Chat Completions

| Endpoint                                                                                            | Method | Description                                                 |
| --------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------- |
| [`/v1/chat/completions`](/api-reference/endpoints/openAI/creates-a-completion-for-the-chat-message) | `POST` | Generate text, analyze images, call tools, stream responses |
| `/v1/chat/completions/{completion_id}`                                                              | `GET`  | Retrieve a stored chat completion by ID                     |
| `/v1/chat/completions/{completion_id}/messages`                                                     | `GET`  | List messages from a stored chat completion                 |

#### Images

| Endpoint                                                                                                                                      | Method | Description                       |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------------------------------- |
| [`/v1/images/generations`](/api-reference/endpoints/openAI/generates-a-batch-of-images-from-a-text-caption-on-a-given-dalle-model-deployment) | `POST` | Generate images from text prompts |
| `/v1/images/edits`                                                                                                                            | `POST` | Edit or extend existing images    |
| `/v1/images/variations`                                                                                                                       | `POST` | Generate variations of an image   |

### Developer Preview

These endpoints are available on the Hicap developer API and are not yet in production.

<Note>
  Developer preview endpoints may change before general availability. Contact [support@hicap.ai](mailto:support@hicap.ai) for access.
</Note>

#### Responses

| Endpoint                                  | Method         | Description                             |
| ----------------------------------------- | -------------- | --------------------------------------- |
| `/v1/responses`                           | `POST`         | Create a model response (Responses API) |
| `/v1/responses/{response_id}`             | `GET` `DELETE` | Retrieve or delete a response           |
| `/v1/responses/{response_id}/cancel`      | `POST`         | Cancel an in-progress response          |
| `/v1/responses/{response_id}/input_items` | `GET`          | List input items for a response         |

#### Realtime

| Endpoint                              | Method | Description                    |
| ------------------------------------- | ------ | ------------------------------ |
| `/v1/realtime/sessions`               | `POST` | Create a realtime session      |
| `/v1/realtime/transcription_sessions` | `POST` | Create a transcription session |

***

## Models

Pass any [supported model ID](https://hicap.ai/models) in the `model` field. The Hicap API supports models across OpenAI, Anthropic, Google Gemini, Moonshot, Zhipu, and MiniMax — all through the same OpenAI-compatible interface.

[View all models →](https://hicap.ai/models)

***

## Streaming

Most text generation endpoints support server-sent events (SSE) for streaming responses. Set `"stream": true` in your request body to receive chunks as they are generated.

```bash theme={null}
curl https://api.hicap.ai/v1/chat/completions \
  -H "Authorization: Bearer $HICAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Write a haiku"}],
    "stream": true
  }'
```

Each SSE event contains a JSON chunk with incremental content. The stream ends with a `[DONE]` sentinel.

***

## Rate limits

Rate limits vary by plan and are applied per API key. When you exceed your limit, the API returns a `429` status code. Use exponential backoff to retry.

The following rate limit headers are included in API responses:

| Header                           | Description                                |
| -------------------------------- | ------------------------------------------ |
| `x-ratelimit-limit-requests`     | Max requests allowed in the current window |
| `x-ratelimit-limit-tokens`       | Max tokens allowed in the current window   |
| `x-ratelimit-remaining-requests` | Requests remaining in the current window   |
| `x-ratelimit-remaining-tokens`   | Tokens remaining in the current window     |
| `x-ratelimit-reset-requests`     | Time until the request limit resets        |
| `x-ratelimit-reset-tokens`       | Time until the token limit resets          |

For higher limits, contact [support@hicap.ai](mailto:support@hicap.ai) or upgrade your plan in the [Hicap Platform ↗](https://platform.hicap.ai/).

***

## Errors

The Hicap API uses standard HTTP status codes and returns JSON error bodies.

| Status | Type                    | Description                                               |
| ------ | ----------------------- | --------------------------------------------------------- |
| `400`  | `invalid_request_error` | Malformed request body or missing required fields         |
| `401`  | `authentication_error`  | Invalid or missing API key                                |
| `403`  | `permission_error`      | API key lacks required permissions                        |
| `404`  | `not_found_error`       | Requested resource does not exist                         |
| `429`  | `rate_limit_error`      | Rate limit exceeded — back off and retry                  |
| `500`  | `api_error`             | Internal server error — retry with exponential backoff    |
| `503`  | `overloaded_error`      | Server temporarily overloaded — retry after a short delay |

Error responses include a JSON body:

```json theme={null}
{
  "error": {
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

***

## Request IDs

Every API response includes an `x-request-id` header with a unique identifier for that request. Log this value in production — it allows the Hicap support team to quickly locate and diagnose issues if you need help.

***

## Versioning

The Hicap API follows the OpenAI v1 API specification. We are committed to maintaining backward compatibility within the v1 API and will avoid breaking changes whenever possible.