---
url: /docs/api/openai-responses.md
---
# OpenAI Responses

`POST /v1/responses`

OpenAI Responses API compatible endpoint. This is a standard pass-through.

See [OpenAI's documentation](https://developers.openai.com/api/reference/resources/responses/methods/create)
for the full request and response specification.

## Request

```bash
curl https://hyper.charm.land/v1/responses \
  -H "Authorization: Bearer sk-hyper-xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-pro",
    "input": "What is bubble tea?"
  }'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `model` | string | yes | Model ID from [`/v1/models`](/api/list-models) |
| `input` | string or array | yes | A string prompt or array of message objects |

All standard Responses API parameters are accepted.

## Response

```json
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1718000000,
  "model": "deepseek-v4-pro",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Bubble tea is a Taiwanese drink..."
        }
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 42,
    "total_tokens": 50
  }
}
```

## Errors

All errors use the standard OpenAI error format:

```json
{
  "error": {
    "message": "...",
    "type": "...",
    "code": null
  }
}
```

| Status | `error.type` | Cause |
|--------|-------------|-------|
| 400 | `invalid_request_error` | Invalid JSON, missing `model` or `input`, context window exceeded |
| 401 | `authentication_error` | Missing or invalid API key |
| 402 | `billing_error` | Insufficient Hypercredits |
| 403 | `permission_error` | Forbidden |
| 404 | `invalid_request_error` | Model not found |
| 429 | `rate_limit_error` | Rate limit exceeded |
| 5xx | `server_error` | Upstream provider failure |