Create chat completion
OpenAI-compatible Chat Completions: shared by GPT, Gemini, GLM, Qwen, DeepSeek, Grok, Claude and other chat models.
/v1/chat/completionsGiven a list of messages, returns the model's reply. With the OpenAI SDK, just set the Base URL to https://api.hop-base.com/v1 and use an API key from the matching group.
The table lists only the fields the gateway checks, rewrites or rejects, plus values documented on each model page; OpenAI fields not listed are forwarded as-is, with ranges per the model's official spec. The whole request body is capped at 60 MB; larger bodies return 413.
Claude models can also use this endpoint with a key from a Claude group; billing is identical to /v1/messages. When max_tokens is omitted, it defaults to 16000 for non-streaming and 64000 for streaming requests, capped at the model's output limit. Claude models do not use temperature / top_p; if sent, they are ignored without an error. n greater than 1, the legacy functions / function_call fields, and audio input return 400. Thinking blocks are not passed back between tool-call turns, so prefer /v1/messages when your client supports the Anthropic protocol. /v1/responses does not support Claude models and returns 404.
Charged non-streaming responses return the actual charge for this request: the X-HopBase-Cost / X-HopBase-Cost-USD / X-HopBase-Currency headers, plus cost / cost_usd / currency in the top-level usage object of the body (existing usage fields are kept). cost_usd is the USD amount actually deducted from your balance; cost is the same charge in CNY, and currency is always CNY. Streaming (SSE) responses do not carry it; check Usage in the console. Uncharged responses, such as errors, carry neither. See Account API · Charges.
Headers
Bearer sk-…: an API key created in the console under API keys; its group must include the requested model
Body parametersJSON
A model ID in the current key's group; GET /v1/models is authoritative. If the group does not include the model, returns 404 model_not_found; image models such as gpt-image-* return 400 image models do not support Chat Completions, please use the Images API on this endpoint
Conversation messages. Missing returns 400 missing messages field; an empty array returns 400 messages must not be an empty array
Items≥ 1
system / user / assistant / tool, in OpenAI format
A string, or an array of content parts. Part {"type": "text", "text": …}; vision models also accept {"type": "image_url", "image_url": {"url": …}}. Per-model image requirements are shown under the model picker above
text or image_url
Text when type is text
Image when type is image_url
HTTP(S) link or data: URI; supported forms vary by model
assistant only: the tool calls returned by the model in the previous turn, sent back unchanged
tool only: must match tool_calls[].id from the previous turn
Output cap. The gateway does not truncate or rewrite it; the limit follows the model's official spec, and values above it return an error from the model
Same as max_tokens; the newer OpenAI field name
true returns SSE; see Streaming events for the event format
Defaultfalse
Streaming options
When streaming, pass true to receive a final event carrying only usage (with empty choices); if omitted it is not sent. Billing is unaffected
Defaultfalse
Function tools in OpenAI function tools format, forwarded as-is.
Always function
Function name
What the function does; the model uses it to decide whether to call it
JSON Schema for the parameters
auto / none / required or a specific function, forwarded as-is
Sampling temperature, forwarded as-is; range per the model's official spec
Nucleus sampling, forwarded as-is; range per the model's official spec
Reasoning effort. Values vary by model; select a model family above to see them
Only priority / flex are kept; other values are removed before forwarding, without an error. priority takes effect only in groups that support it and is billed at the Fast price; elsewhere the request runs on the standard tier at the standard price. The "GPT Official Direct (Azure)" group does not support priority
Valuespriorityflex
A model ID in the current key's group; GET /v1/models is authoritative. If the group does not include the model, returns 404 model_not_found; image models such as gpt-image-* return 400 image models do not support Chat Completions, please use the Images API on this endpoint
Valuescodex-auto-reviewgpt-4.1gpt-4.1-minigpt-4.1-nanogpt-4ogpt-4o-minigpt-5gpt-5-minigpt-5-nanogpt-5.1gpt-5.2gpt-5.3-codex-sparkgpt-5.4gpt-5.4-minigpt-5.4-nanogpt-5.4-progpt-5.5gpt-5.6-lunagpt-5.6-solgpt-5.6-terragpt-6-astragpt-6-lunagpt-6-solgpt-6.1-solgpt-6.1-terragpt-6.2-astragpt-6.2-sol
Conversation messages. Missing returns 400 missing messages field; an empty array returns 400 messages must not be an empty array
Items≥ 1
system / user / assistant / tool, in OpenAI format
A string, or an array of content parts. Part {"type": "text", "text": …}; vision models also accept {"type": "image_url", "image_url": {"url": …}}. Per-model image requirements are shown under the model picker above
text or image_url
Text when type is text
Image when type is image_url
HTTP(S) link or data: URI; supported forms vary by model
assistant only: the tool calls returned by the model in the previous turn, sent back unchanged
tool only: must match tool_calls[].id from the previous turn
Output cap. The gateway does not truncate or rewrite it; the limit follows the model's official spec, and values above it return an error from the model
Same as max_tokens; the newer OpenAI field name
true returns SSE; see Streaming events for the event format
Defaultfalse
Streaming options
When streaming, pass true to receive a final event carrying only usage (with empty choices); if omitted it is not sent. Billing is unaffected
Defaultfalse
Function tools in OpenAI function tools format, forwarded as-is.
Always function
Function name
What the function does; the model uses it to decide whether to call it
JSON Schema for the parameters
auto / none / required or a specific function, forwarded as-is
Sampling temperature, forwarded as-is; range per the model's official spec
Nucleus sampling, forwarded as-is; range per the model's official spec
Reasoning effort. Values vary by model; select a model family above to see them
Only priority / flex are kept; other values are removed before forwarding, without an error. priority takes effect only in groups that support it and is billed at the Fast price; elsewhere the request runs on the standard tier at the standard price. The "GPT Official Direct (Azure)" group does not support priority
Valuespriorityflex
A model ID in the current key's group; GET /v1/models is authoritative. If the group does not include the model, returns 404 model_not_found; image models such as gpt-image-* return 400 image models do not support Chat Completions, please use the Images API on this endpoint
Valuesgemini-2.5-flashgemini-2.5-flash-litegemini-2.5-progemini-3-flash-previewgemini-3.1-flash-litegemini-3.1-flash-lite-previewgemini-3.1-pro-previewgemini-3.1-pro-preview-customtoolsgemini-3.5-flashgemini-3.5-flash-litegemini-3.6-flashgemini-3.7-flashgemini-3.8-flashgemini-4-argongemini-4-carbongemini-4-hydrogengemini-4-neon
Supported content parts: text, image_url, input_audio, file, and refusal; other types (such as video_url) return 400. image_url accepts base64 data URLs only (public links return 400 image_url only supports data URLs (base64-embedded images)); file.file_data must be a data URL, and file_id is not supported; role: "tool" is sent to the model as a function result; no usable content returns 400
Items≥ 1
system / user / assistant / tool, in OpenAI format
A string, or an array of content parts. Part {"type": "text", "text": …}; vision models also accept {"type": "image_url", "image_url": {"url": …}}. Per-model image requirements are shown under the model picker above
text or image_url
Text when type is text
Image when type is image_url
HTTP(S) link or data: URI; supported forms vary by model
assistant only: the tool calls returned by the model in the previous turn, sent back unchanged
tool only: must match tool_calls[].id from the previous turn
If max_completion_tokens is also sent, max_tokens wins. Thinking tokens count toward this cap; 4096 or more is recommended
Same as max_tokens; the newer OpenAI field name
true returns SSE; see Streaming events for the event format
Defaultfalse
Streaming options
When streaming, pass true to receive a final event carrying only usage (with empty choices); if omitted it is not sent. Billing is unaffected
Defaultfalse
Function tools in OpenAI function tools format, forwarded as-is.
Always function
Function name
What the function does; the model uses it to decide whether to call it
JSON Schema for the parameters
auto / none / required, a specific function, or allowed_tools; parallel calls and multi-turn are supported, and parallel_tool_calls: false keeps only the first call
Sampling temperature, forwarded as-is; range per the model's official spec
Nucleus sampling, forwarded as-is; range per the model's official spec
none / minimal → thinking budget 0; medium → 8192; high → 24576; low and other values keep the model default
Valuesnoneminimallowmediumhigh
Only priority / flex are kept; other values are removed before forwarding, without an error. priority takes effect only in groups that support it and is billed at the Fast price; elsewhere the request runs on the standard tier at the standard price. The "GPT Official Direct (Azure)" group does not support priority
Valuespriorityflex
A model ID in the current key's group; GET /v1/models is authoritative. If the group does not include the model, returns 404 model_not_found; image models such as gpt-image-* return 400 image models do not support Chat Completions, please use the Images API on this endpoint
Valuesglm-5.3
Non-empty array, text only; images return 400. 1M context
Items≥ 1
system / user / assistant / tool, in OpenAI format
A string, or an array of content parts. Part {"type": "text", "text": …}; vision models also accept {"type": "image_url", "image_url": {"url": …}}. Per-model image requirements are shown under the model picker above
text or image_url
Text when type is text
Image when type is image_url
HTTP(S) link or data: URI; supported forms vary by model
assistant only: the tool calls returned by the model in the previous turn, sent back unchanged
tool only: must match tool_calls[].id from the previous turn
Shared by thinking and answer. Out of range returns 400 max_tokens invalid: allowed range [1,131072]
Range1–131072
Same as max_tokens; the newer OpenAI field name
true returns SSE; see Streaming events for the event format
Defaultfalse
Streaming options
When streaming, pass true to receive a final event carrying only usage (with empty choices); if omitted it is not sent. Billing is unaffected
Defaultfalse
Function tools in OpenAI function tools format, forwarded as-is.
Always function
Function name
What the function does; the model uses it to decide whether to call it
JSON Schema for the parameters
Same as OpenAI. Returned tool results must match a call ID from the previous turn, otherwise 400 No tool call found for function call output
Default"auto"
Sampling temperature, forwarded as-is; range per the model's official spec
Nucleus sampling, forwarded as-is; range per the model's official spec
Always thinks: values that disable thinking, such as none, return 400
Valueslowhighmax
Only priority / flex are kept; other values are removed before forwarding, without an error. priority takes effect only in groups that support it and is billed at the Fast price; elsewhere the request runs on the standard tier at the standard price. The "GPT Official Direct (Azure)" group does not support priority
Valuespriorityflex
A model ID in the current key's group; GET /v1/models is authoritative. If the group does not include the model, returns 404 model_not_found; image models such as gpt-image-* return 400 image models do not support Chat Completions, please use the Images API on this endpoint
Valuesglm-5.3-flash
Non-empty array; may contain text, images, video and files. 1M context
Items≥ 1
system / user / assistant / tool, in OpenAI format
A string, or an array of content parts. Part {"type": "text", "text": …}; vision models also accept {"type": "image_url", "image_url": {"url": …}}. Per-model image requirements are shown under the model picker above
text or image_url
Text when type is text
Image when type is image_url
HTTP(S) link or data: URI; supported forms vary by model
assistant only: the tool calls returned by the model in the previous turn, sent back unchanged
tool only: must match tool_calls[].id from the previous turn
Up to 128K (official cap), shared by thinking and answer
Same as max_tokens; the newer OpenAI field name
true returns SSE; see Streaming events for the event format
Defaultfalse
Streaming options
When streaming, pass true to receive a final event carrying only usage (with empty choices); if omitted it is not sent. Billing is unaffected
Defaultfalse
Function tools in OpenAI function tools format, forwarded as-is.
Always function
Function name
What the function does; the model uses it to decide whether to call it
JSON Schema for the parameters
auto / none / required or a specific function, forwarded as-is
No gateway range; 1 recommended
No gateway range; 0.95 recommended
max recommended; thinking can only be on, not off
Valueslowhighmax
Only priority / flex are kept; other values are removed before forwarding, without an error. priority takes effect only in groups that support it and is billed at the Fast price; elsewhere the request runs on the standard tier at the standard price. The "GPT Official Direct (Azure)" group does not support priority
Valuespriorityflex
Recommended true when streaming with tools, so tool arguments stream incrementally
Defaultfalse
A model ID in the current key's group; GET /v1/models is authoritative. If the group does not include the model, returns 404 model_not_found; image models such as gpt-image-* return 400 image models do not support Chat Completions, please use the Images API on this endpoint
Valuesqwen3.7-maxqwen3.7-plusqwen3.8-flashqwen3.8-maxqwen4-max
Non-empty array; qwen3.7-max is text only, other models accept images and video; image width and height must exceed 10 px. qwen3.8-max measured input cap is 991,808 tokens; beyond that returns 400 Range of input length should be [1, 991808]
Items≥ 1
system / user / assistant / tool, in OpenAI format
A string, or an array of content parts. Part {"type": "text", "text": …}; vision models also accept {"type": "image_url", "image_url": {"url": …}}. Per-model image requirements are shown under the model picker above
text or image_url
Text when type is text
Image when type is image_url
HTTP(S) link or data: URI; supported forms vary by model
assistant only: the tool calls returned by the model in the previous turn, sent back unchanged
tool only: must match tool_calls[].id from the previous turn
Up to 131,072 (official cap)
Range≤ 131072
Same as max_tokens; the newer OpenAI field name
true returns SSE; see Streaming events for the event format
Defaultfalse
Streaming options
When streaming, pass true to receive a final event carrying only usage (with empty choices); if omitted it is not sent. Billing is unaffected
Defaultfalse
Function tools in OpenAI function tools format, forwarded as-is.
Always function
Function name
What the function does; the model uses it to decide whether to call it
JSON Schema for the parameters
Same as OpenAI. In thinking mode it cannot be required or a specific function; doing so returns 400
Default"auto"
Sampling temperature, forwarded as-is; range per the model's official spec
Nucleus sampling, forwarded as-is; range per the model's official spec
Values verified to work
Valueslowhighmax
Only priority / flex are kept; other values are removed before forwarding, without an error. priority takes effect only in groups that support it and is billed at the Fast price; elsewhere the request runs on the standard tier at the standard price. The "GPT Official Direct (Azure)" group does not support priority
Valuespriorityflex
Qwen-specific, passed through
Cannot be set together with reasoning_effort; doing so returns 400
Qwen-specific, passed through
JSON mode, same behavior as the official API
A model ID in the current key's group; GET /v1/models is authoritative. If the group does not include the model, returns 404 model_not_found; image models such as gpt-image-* return 400 image models do not support Chat Completions, please use the Images API on this endpoint
Valuesdeepseek-v4-flash-202605deepseek-v4-pro-202606deepseek-v4.1-flashdeepseek-v4.1-flash-1017deepseek-v4.1-flash-1017-sg
Non-empty array; role is system / user / assistant / tool / developer. Image input on deepseek-v4.1-flash and deepseek-v4.1-flash-1017 only: image_url.url may be a data: URI or an https:// link
Items≥ 1
system / user / assistant / tool, in OpenAI format
A string, or an array of content parts. Part {"type": "text", "text": …}; vision models also accept {"type": "image_url", "image_url": {"url": …}}. Per-model image requirements are shown under the model picker above
text or image_url
Text when type is text
Image when type is image_url
HTTP(S) link or data: URI; supported forms vary by model
assistant only: the tool calls returned by the model in the previous turn, sent back unchanged
tool only: must match tool_calls[].id from the previous turn
Non-negative integer; output caps: V4.1 Flash and V4 Flash 384,000, V4 Pro 393,216. Shared by thinking and answer; negative values return 400; values above the cap do not error, the output is silently truncated
Range≥ 0
Same as max_tokens; the newer OpenAI field name
true returns SSE; see Streaming events for the event format
Defaultfalse
Streaming options
When streaming, pass true to receive a final event carrying only usage (with empty choices); if omitted it is not sent. Billing is unaffected
Defaultfalse
Function tools in OpenAI function tools format, forwarded as-is.
Always function
Function name
What the function does; the model uses it to decide whether to call it
JSON Schema for the parameters
auto / none / required / a specific function
Default"auto"
Values above 2 return 400 expected a value <= 2
Range0–2
Nucleus sampling, forwarded as-is; range per the model's official spec
Values verified to work
Valueslowmediumhigh
Only priority / flex are kept; other values are removed before forwarding, without an error. priority takes effect only in groups that support it and is billed at the Fast price; elsewhere the request runs on the standard tier at the standard price. The "GPT Official Direct (Azure)" group does not support priority
Valuespriorityflex
{"type": …}; other values (such as auto) return 400. On by default for V4.1 Flash
Valuesenableddisabledadaptive
Prefix continuation: only allowed on the last assistant message
Defaultfalse
A model ID in the current key's group; GET /v1/models is authoritative. If the group does not include the model, returns 404 model_not_found; image models such as gpt-image-* return 400 image models do not support Chat Completions, please use the Images API on this endpoint
Valuesdoubao-seed-2-0-mini-260428doubao-seed-2-1-lite-260915doubao-seed-2-1-pro-260628doubao-seed-2-1-pro-260915doubao-seed-2-1-turbo-260628doubao-seed-character-260628doubao-seed-evolving
Non-empty array; all seven models accept images: image_url.url is a publicly downloadable link or a data: URI (base64)
Items≥ 1
system / user / assistant / tool, in OpenAI format
A string, or an array of content parts. Part {"type": "text", "text": …}; vision models also accept {"type": "image_url", "image_url": {"url": …}}. Per-model image requirements are shown under the model picker above
text or image_url
Text when type is text
Image when type is image_url
HTTP(S) link or data: URI; supported forms vary by model
assistant only: the tool calls returned by the model in the previous turn, sent back unchanged
tool only: must match tool_calls[].id from the previous turn
doubao-seed-2-1-pro-260915 and doubao-seed-2-1-lite-260915 up to 256K; doubao-seed-character-260628 up to 32K; the others up to 128K
Same as max_tokens; the newer OpenAI field name
true returns SSE; see Streaming events for the event format
Defaultfalse
Streaming options
When streaming, pass true to receive a final event carrying only usage (with empty choices); if omitted it is not sent. Billing is unaffected
Defaultfalse
Function tools in OpenAI function tools format, forwarded as-is.
Always function
Function name
What the function does; the model uses it to decide whether to call it
JSON Schema for the parameters
doubao-seed-evolving and doubao-seed-2-1-pro-260915 ignore it: with none or a named function they still pick tools on their own; to force or disable tool calls, use doubao-seed-2-1-pro-260628 or doubao-seed-2-1-lite-260915
Default"auto"
Sampling temperature, forwarded as-is; range per the model's official spec
Nucleus sampling, forwarded as-is; range per the model's official spec
Reasoning effort. Values vary by model; select a model family above to see them
Only priority / flex are kept; other values are removed before forwarding, without an error. priority takes effect only in groups that support it and is billed at the Fast price; elsewhere the request runs on the standard tier at the standard price. The "GPT Official Direct (Azure)" group does not support priority
Valuespriorityflex
A model ID in the current key's group; GET /v1/models is authoritative. If the group does not include the model, returns 404 model_not_found; image models such as gpt-image-* return 400 image models do not support Chat Completions, please use the Images API on this endpoint
Valuesdeepseek-v4-flash-usdeepseek-v4-pro-usdeepseek-v4.1-flash-usglm-5.2-usglm-5.3-us
Non-empty array. Image input on deepseek-v4.1-flash-us only; the other models do not see images. Context 1M
Items≥ 1
system / user / assistant / tool, in OpenAI format
A string, or an array of content parts. Part {"type": "text", "text": …}; vision models also accept {"type": "image_url", "image_url": {"url": …}}. Per-model image requirements are shown under the model picker above
text or image_url
Text when type is text
Image when type is image_url
HTTP(S) link or data: URI; supported forms vary by model
assistant only: the tool calls returned by the model in the previous turn, sent back unchanged
tool only: must match tool_calls[].id from the previous turn
Shared by thinking and answer. GLM caps at 131,072; above it returns 400 Range of max_tokens should be [1, 131072]. DeepSeek caps at 393,216; above it is not rejected
Range≥ 1
Same as max_tokens; the newer OpenAI field name
true returns SSE; see Streaming events for the event format
Defaultfalse
Streaming options
When streaming, pass true to receive a final event carrying only usage (with empty choices); if omitted it is not sent. Billing is unaffected
Defaultfalse
Function tools in OpenAI function tools format, forwarded as-is.
Always function
Function name
What the function does; the model uses it to decide whether to call it
JSON Schema for the parameters
Same as OpenAI. GLM ignores a forced choice (required or a specific function) and may answer in text
Default"auto"
GLM must be below 2.0, otherwise 400 Temperature should be in [0.0, 2.0)
Range0–2
Nucleus sampling, forwarded as-is; range per the model's official spec
Reasoning effort. Values vary by model; select a model family above to see them
Only priority / flex are kept; other values are removed before forwarding, without an error. priority takes effect only in groups that support it and is billed at the Fast price; elsewhere the request runs on the standard tier at the standard price. The "GPT Official Direct (Azure)" group does not support priority
Valuespriorityflex
DeepSeek accepts only 1; other values return 400
Range≥ 1
Must be true on glm-5.3-us; false returns 400
A model ID in the current key's group; GET /v1/models is authoritative. If the group does not include the model, returns 404 model_not_found; image models such as gpt-image-* return 400 image models do not support Chat Completions, please use the Images API on this endpoint
Valuesgrok-4.20-0309-reasoninggrok-4.20-multi-agent-0309grok-4.3grok-4.5grok-4.6grok-4.7
Conversation messages. Missing returns 400 missing messages field; an empty array returns 400 messages must not be an empty array
Items≥ 1
system / user / assistant / tool, in OpenAI format
A string, or an array of content parts. Part {"type": "text", "text": …}; vision models also accept {"type": "image_url", "image_url": {"url": …}}. Per-model image requirements are shown under the model picker above
text or image_url
Text when type is text
Image when type is image_url
HTTP(S) link or data: URI; supported forms vary by model
assistant only: the tool calls returned by the model in the previous turn, sent back unchanged
tool only: must match tool_calls[].id from the previous turn
No gateway cap; bounded by the context window. Officially includes reasoning tokens
Same as max_tokens; the newer OpenAI field name
true returns SSE; see Streaming events for the event format
Defaultfalse
Streaming options
When streaming, pass true to receive a final event carrying only usage (with empty choices); if omitted it is not sent. Billing is unaffected
Defaultfalse
Function tools and server-side tools; server-side tools are billed per call
auto / none / required or a specific function, forwarded as-is
0–2 (official)
Range0–2
0–1 (official); officially recommended to use either this or temperature, not both
Range0–1
grok-4.7 / grok-4.6: low / medium / high / xhigh; grok-4.5: low / medium / high (official). Only these three models expose it officially; reasoning cannot be disabled
Valueslowmediumhighxhigh
Default"high"
Only priority / flex are kept; other values are removed before forwarding, without an error. priority takes effect only in groups that support it and is billed at the Fast price; elsewhere the request runs on the standard tier at the standard price. The "GPT Official Direct (Azure)" group does not support priority
Valuespriorityflex
Not supported (official): reasoning models reject it and return an error
Not supported (official)
Not supported (official)
Returns
200Success. Non-streaming returns chat.completion JSON; with stream: true it returns SSE (text/event-stream)
Response headers
The charge for this request in CNY (the same charge as X-HopBase-Cost-USD), up to 6 decimal places, such as 0.0816. Sent only when the request is charged; not sent on streaming (SSE) responses. When image generation takes longer than about 40 seconds the headers have already been sent, so read usage.cost in the body instead
The USD amount actually deducted from your balance for this request, the same amount as its usage record, up to 8 decimal places, such as 0.012; sent only together with X-HopBase-Cost
The currency of X-HopBase-Cost, always CNY
ID of this completion
Always chat.completion
Unix seconds
Model ID actually used
Candidate replies; most models return only 1
Index
Model reply
Always assistant
Reply text; null when the model only calls tools
Reasoning content (returned by DeepSeek and other models)
Functions the model wants to call; after running them, send the results back in role: "tool" messages
Call ID; put it in tool_call_id when returning the result
Function name
Arguments as a JSON string
stop / length / tool_calls, etc.; length means the output cap was hit
Token usage
Input tokens
Output tokens; whether reasoning tokens are included varies by model, see each model page
Total
Reasoning tokens (listed separately by some models)
Added by the gateway: the charge for this request in CNY (the same charge as cost_usd), the same as the X-HopBase-Cost header; not returned when streaming
Added by the gateway: the USD amount actually deducted from your balance, the same as the X-HopBase-Cost-USD header and your usage record; not returned when streaming
Added by the gateway: the currency of cost, always CNY
Errors
messages, etc.missing_api_key / invalid_api_key / api_key_expired)insufficient_quota)model_not_found), or the path does not belong to the group (route_not_found)request_too_large)user_concurrency_limit / apikey_concurrency_limit), with Retry-After