Endpoint reference
The /v1 endpoints with parameters and responses, generated from the OpenAPI spec.
This page is generated from the OpenAPI spec. The descriptions come from the spec as written.
Authentication
Authorization: Bearer <hvd_... key>
POST /v1/chat/completions
OpenAI-compatible chat completion (JSON or SSE). hvd_... developer key or a dashboard JWT. With stream: true the response is text/event-stream (data: {chat.completion.chunk} lines, terminated by data: [DONE]). Unknown fields are ignored. Body limit OPENAI_API_MAX_REQUEST_MB (40). Errors always use the OpenAI envelope, **including 401**.
Request body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
| model | string | Yes | Catalog slug or auto. |
| messages | object[] | Yes | |
| max_tokens | integer | No | |
| max_completion_tokens | integer | No | |
| temperature | number | No | |
| stream | boolean | No | |
| stream_options | object | No |
Success response fields
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | |
| object | "chat.completion" | Yes | |
| created | integer | Yes | |
| model | string | Yes | |
| choices | object[] | Yes | |
| usage | object | Yes |
Responses
| Status | Description |
|---|---|
| 200 | Completion (JSON) or event stream. |
| 400 | invalid_json, missing_required_parameter, invalid_type, invalid_value, unsupported_value, invalid_image_url, too_many_images. |
| 401 | invalid_api_key / token_expired / session_revoked. |
| 402 | insufficient_credits / quota_exceeded (+ wallet_balance_units, quota_code). |
| 403 | model_requires_paid_plan / content_blocked. |
| 404 | model_not_found. |
| 413 | request_too_large. |
| 415 | |
| 422 | context_length_exceeded / model_does_not_support_images. Also {"msg": ...} for a malformed/wrong-type token. |
| 429 | rate_limit_exceeded or too_many_concurrent; carries Retry-After. |
| 500 | internal_error. |
| 502 | provider_error (provider failure or empty answer). |
| 503 | model_unavailable / service_unavailable (+ Retry-After). |
| 504 | provider_timeout. |
GET /v1/models
List models usable by the caller's plan
Success response fields
| Name | Type | Required | Description |
|---|---|---|---|
| object | "list" | Yes | |
| data | object[] | Yes |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 401 | invalid_api_key / token_expired / session_revoked. |
| 422 | |
| 429 | rate_limit_exceeded or too_many_concurrent; carries Retry-After. |
| 500 | internal_error. |
| 503 | service_unavailable: catalog not seeded. |
GET /v1/models/{model_id}
Retrieve one model
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| model_id | string | Yes | path |
Success response fields
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | |
| object | "model" | Yes | |
| created | integer | Yes | |
| owned_by | "hoveydai" | Yes | |
| context_window | integer | No | |
| max_output_tokens | integer | No | |
| supports_vision | boolean | No |
Responses
| Status | Description |
|---|---|
| 200 | OK |
| 401 | invalid_api_key / token_expired / session_revoked. |
| 404 | model_not_found. |
| 422 | |
| 429 | rate_limit_exceeded or too_many_concurrent; carries Retry-After. |
| 500 | internal_error. |
| 503 | service_unavailable. |
Error shape
Every /v1 error response has this shape:
| Name | Type | Required | Description |
|---|---|---|---|
| message | string | Yes | |
| type | "invalid_request_error" | "insufficient_credits" | "permission_error" | "rate_limit_error" | "server_error" | Yes | |
| param | string | null | Yes | |
| code | string | Yes | Stable code, e.g. invalid_api_key, token_expired, session_revoked, invalid_json, missing_required_parameter, invalid_type, invalid_value, unsupported_value, model_not_found, model_requires_paid_plan, insufficient_credits, quota_exceeded, context_length_exceeded, request_too_large, rate_limit_exceeded, too_many_concurrent, model_unavailable, service_unavailable, provider_timeout, provider_error, content_blocked, internal_error, unknown_url, method_not_allowed. |
| request_id | string | No | Also sent as the x-request-id header. |
| quota_code | string | No | |
| wallet_balance_units | integer | No | |
| suggested_models | string[] | No |
Source: docs/openapi.yaml
Did this page not help? Tell us.