مرجع نقطه‌های پایانی | مستندات هویدای

مسیرها، پارامترها و پاسخ‌های API در یک صفحه.

احراز هویت

Authorization: Bearer <کلید hvd_...>

POST /v1/chat/completions

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 40 MB. Errors always use the standard error envelope, **including 401**.

بدنهٔ درخواست (JSON)

بدنهٔ درخواست (JSON)
نام	نوع	الزامی	توضیح
model	string	بله	A public model id from GET /v1/models (an old catalog slug still works as an alias), or auto.
messages	object[]	بله
max_tokens	integer	خیر
max_completion_tokens	integer	خیر
temperature	number	خیر
top_p	number	خیر
stop	string \| string[]	خیر
n	1	خیر	Only 1 is supported; any other value is refused with 400 unsupported_value.
stream	boolean	خیر
stream_options	object	خیر

فیلدهای پاسخ موفق

فیلدهای پاسخ موفق
نام	نوع	الزامی
id	string	بله
object	"chat.completion"	بله
created	integer	بله
model	string	بله
choices	object[]	بله
usage	object	بله

پاسخ‌ها

پاسخ‌ها
وضعیت	توضیح
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 the public models the key can call (list shape; ids are public ids such as `vendor/model`)

فیلدهای پاسخ موفق

فیلدهای پاسخ موفق
نام	نوع	الزامی	توضیح
object	"list"	بله
data	object[]	بله

پاسخ‌ها

پاسخ‌ها
وضعیت	توضیح
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

پارامترهای مسیر

پارامترهای مسیر
نام	نوع	الزامی	توضیح
model_id	string	بله	path

فیلدهای پاسخ موفق

فیلدهای پاسخ موفق
نام	نوع	الزامی	توضیح
id	string	بله	Public model id, e.g. vendor/model.
object	"model"	بله
created	integer	بله
owned_by	"hoveydai"	بله
context_window	integer	خیر
max_output_tokens	integer	خیر
supports_vision	boolean	خیر

پاسخ‌ها

پاسخ‌ها
وضعیت	توضیح
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.

قالب خطا

همهٔ پاسخ‌های خطای /v1 این قالب را دارند:

قالب خطا
نام	نوع	الزامی	توضیح
message	string	بله
type	"invalid_request_error" \| "authentication_error" \| "insufficient_quota" \| "permission_error" \| "rate_limit_error" \| "api_error"	بله
param	string \| null	بله
code	string	بله	Stable code, e.g. invalid_api_key, token_expired, session_revoked, invalid_json, missing_required_parameter, invalid_type, invalid_value, unsupported_value, invalid_image_url, too_many_images, 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	خیر	Also sent as the x-request-id header.
quota_code	string	خیر
wallet_balance_units	integer	خیر
suggested_models	string[]	خیر