Create completions — POST /v1/completions

Implements the OpenAI-compatible chat completions API

POST /v1/completions

AI → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/completions`
Method	`POST`
Operation	`post_completions`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Implements the OpenAI-compatible chat completions API

Request

69 fields, body application/json (required).

Field	In	Type	Required	Description
`X-Max-Cost`	header	number	—	The most this request may cost, in USD per 1,000 tokens.
`X-Max-Latency-Ms`	header	integer	—	The slowest model this request accepts, in milliseconds.
`frequency_penalty`	body	number	—
`function_call`	body	any	—
`functions`	body	openai.FunctionDefinition[]	—
`functions[].description`	body	string	—
`functions[].name`	body	string	—
`functions[].parameters`	body	any	—
`functions[].strict`	body	boolean	—
`logit_bias`	body	object	—
`logit_bias.*`	body	integer	—
`logprobs`	body	boolean	—
`max_completion_tokens`	body	integer	—
`max_tokens`	body	integer	—
`messages`	body	openai.ChatCompletionMessage[]	—
`messages[].MultiContent`	body	openai.ChatMessagePart[]	—
`messages[].MultiContent[].image_url`	body	openai.ChatMessageImageURL	—
`messages[].MultiContent[].image_url.detail`	body	string	—
`messages[].MultiContent[].image_url.url`	body	string	—
`messages[].MultiContent[].text`	body	string	—
`messages[].MultiContent[].type`	body	string	—
`messages[].content`	body	string	—
`messages[].function_call`	body	openai.FunctionCall	—
`messages[].function_call.arguments`	body	string	—
`messages[].function_call.name`	body	string	—
`messages[].name`	body	string	—
`messages[].reasoning_content`	body	string	—
`messages[].refusal`	body	string	—
`messages[].role`	body	string	—
`messages[].tool_call_id`	body	string	—
`messages[].tool_calls`	body	openai.ToolCall[]	—
`messages[].tool_calls[].function`	body	openai.FunctionCall	—
`messages[].tool_calls[].function.arguments`	body	string	—
`messages[].tool_calls[].function.name`	body	string	—
`messages[].tool_calls[].id`	body	string	—
`messages[].tool_calls[].index`	body	integer	—
`messages[].tool_calls[].type`	body	string	—
`metadata`	body	object	—
`metadata.*`	body	string	—
`model`	body	string	—
`n`	body	integer	—
`parallel_tool_calls`	body	any	—
`presence_penalty`	body	number	—
`reasoning_effort`	body	string	—
`response_format`	body	openai.ChatCompletionResponseFormat	—
`response_format.json_schema`	body	openai.ChatCompletionResponseFormatJSONSchema	—
`response_format.json_schema.description`	body	string	—
`response_format.json_schema.name`	body	string	—
`response_format.json_schema.schema`	body	any	—
`response_format.json_schema.strict`	body	boolean	—
`response_format.type`	body	string	—
`seed`	body	integer	—
`stop`	body	string[]	—
`store`	body	boolean	—
`stream`	body	boolean	—
`stream_options`	body	openai.StreamOptions	—
`stream_options.include_usage`	body	boolean	—
`temperature`	body	number	—
`tool_choice`	body	any	—
`tools`	body	openai.Tool[]	—
`tools[].function`	body	openai.FunctionDefinition	—
`tools[].function.description`	body	string	—
`tools[].function.name`	body	string	—
`tools[].function.parameters`	body	any	—
`tools[].function.strict`	body	boolean	—
`tools[].type`	body	string	—
`top_logprobs`	body	integer	—
`top_p`	body	number	—
`user`	body	string	—

Response

Status	Body	Meaning
`200`	openai.ChatCompletionResponse	Success.
`401`	—	No credential, or one this service does not accept.
`403`	—	A valid credential that may not do this.

200 body — 90 fields.

Field	In	Type	Always
`choices`	body	openai.ChatCompletionChoice[]	—
`choices[].content_filter_results`	body	openai.ContentFilterResults	—
`choices[].content_filter_results.hate`	body	openai.Hate	—
`choices[].content_filter_results.hate.filtered`	body	boolean	—
`choices[].content_filter_results.hate.severity`	body	string	—
`choices[].content_filter_results.jailbreak`	body	openai.JailBreak	—
`choices[].content_filter_results.jailbreak.detected`	body	boolean	—
`choices[].content_filter_results.jailbreak.filtered`	body	boolean	—
`choices[].content_filter_results.profanity`	body	openai.Profanity	—
`choices[].content_filter_results.profanity.detected`	body	boolean	—
`choices[].content_filter_results.profanity.filtered`	body	boolean	—
`choices[].content_filter_results.self_harm`	body	openai.SelfHarm	—
`choices[].content_filter_results.self_harm.filtered`	body	boolean	—
`choices[].content_filter_results.self_harm.severity`	body	string	—
`choices[].content_filter_results.sexual`	body	openai.Sexual	—
`choices[].content_filter_results.sexual.filtered`	body	boolean	—
`choices[].content_filter_results.sexual.severity`	body	string	—
`choices[].content_filter_results.violence`	body	openai.Violence	—
`choices[].content_filter_results.violence.filtered`	body	boolean	—
`choices[].content_filter_results.violence.severity`	body	string	—
`choices[].finish_reason`	body	string	—
`choices[].index`	body	integer	—
`choices[].logprobs`	body	openai.LogProbs	—
`choices[].logprobs.content`	body	openai.LogProb[]	—
`choices[].logprobs.content[].bytes`	body	string (byte)	—
`choices[].logprobs.content[].logprob`	body	number	—
`choices[].logprobs.content[].token`	body	string	—
`choices[].logprobs.content[].top_logprobs`	body	openai.TopLogProbs[]	—
`choices[].logprobs.content[].top_logprobs[].bytes`	body	string (byte)	—
`choices[].logprobs.content[].top_logprobs[].logprob`	body	number	—
`choices[].logprobs.content[].top_logprobs[].token`	body	string	—
`choices[].message`	body	openai.ChatCompletionMessage	—
`choices[].message.MultiContent`	body	openai.ChatMessagePart[]	—
`choices[].message.MultiContent[].image_url`	body	openai.ChatMessageImageURL	—
`choices[].message.MultiContent[].image_url.detail`	body	string	—
`choices[].message.MultiContent[].image_url.url`	body	string	—
`choices[].message.MultiContent[].text`	body	string	—
`choices[].message.MultiContent[].type`	body	string	—
`choices[].message.content`	body	string	—
`choices[].message.function_call`	body	openai.FunctionCall	—
`choices[].message.function_call.arguments`	body	string	—
`choices[].message.function_call.name`	body	string	—
`choices[].message.name`	body	string	—
`choices[].message.reasoning_content`	body	string	—
`choices[].message.refusal`	body	string	—
`choices[].message.role`	body	string	—
`choices[].message.tool_call_id`	body	string	—
`choices[].message.tool_calls`	body	openai.ToolCall[]	—
`choices[].message.tool_calls[].function`	body	openai.FunctionCall	—
`choices[].message.tool_calls[].function.arguments`	body	string	—
`choices[].message.tool_calls[].function.name`	body	string	—
`choices[].message.tool_calls[].id`	body	string	—
`choices[].message.tool_calls[].index`	body	integer	—
`choices[].message.tool_calls[].type`	body	string	—
`created`	body	integer	—
`id`	body	string	—
`model`	body	string	—
`object`	body	string	—
`prompt_filter_results`	body	openai.PromptFilterResult[]	—
`prompt_filter_results[].content_filter_results`	body	openai.ContentFilterResults	—
`prompt_filter_results[].content_filter_results.hate`	body	openai.Hate	—
`prompt_filter_results[].content_filter_results.hate.filtered`	body	boolean	—
`prompt_filter_results[].content_filter_results.hate.severity`	body	string	—
`prompt_filter_results[].content_filter_results.jailbreak`	body	openai.JailBreak	—
`prompt_filter_results[].content_filter_results.jailbreak.detected`	body	boolean	—
`prompt_filter_results[].content_filter_results.jailbreak.filtered`	body	boolean	—
`prompt_filter_results[].content_filter_results.profanity`	body	openai.Profanity	—
`prompt_filter_results[].content_filter_results.profanity.detected`	body	boolean	—
`prompt_filter_results[].content_filter_results.profanity.filtered`	body	boolean	—
`prompt_filter_results[].content_filter_results.self_harm`	body	openai.SelfHarm	—
`prompt_filter_results[].content_filter_results.self_harm.filtered`	body	boolean	—
`prompt_filter_results[].content_filter_results.self_harm.severity`	body	string	—
`prompt_filter_results[].content_filter_results.sexual`	body	openai.Sexual	—
`prompt_filter_results[].content_filter_results.sexual.filtered`	body	boolean	—
`prompt_filter_results[].content_filter_results.sexual.severity`	body	string	—
`prompt_filter_results[].content_filter_results.violence`	body	openai.Violence	—
`prompt_filter_results[].content_filter_results.violence.filtered`	body	boolean	—
`prompt_filter_results[].content_filter_results.violence.severity`	body	string	—
`prompt_filter_results[].index`	body	integer	—
`system_fingerprint`	body	string	—
`usage`	body	openai.Usage	—
`usage.completion_tokens`	body	integer	—
`usage.completion_tokens_details`	body	openai.CompletionTokensDetails	—
`usage.completion_tokens_details.audio_tokens`	body	integer	—
`usage.completion_tokens_details.reasoning_tokens`	body	integer	—
`usage.prompt_tokens`	body	integer	—
`usage.prompt_tokens_details`	body	openai.PromptTokensDetails	—
`usage.prompt_tokens_details.audio_tokens`	body	integer	—
`usage.prompt_tokens_details.cached_tokens`	body	integer	—
`usage.total_tokens`	body	integer	—

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo completions create

.ts

.py

.go

.rs

.java

import { Configuration, AiApi } from 'hanzoai';

const api = new AiApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postCompletions({ frequency_penalty: 0, function_call: "<function_call>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AiApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AiApi(client).post_completions(frequency_penalty=0, function_call="<function_call>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.AiAPI.PostCompletions(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, ai_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = ai_api::post_completions(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AiApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new AiApi(client).postCompletions();

curl -X POST https://api.hanzo.ai/v1/completions \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "frequency_penalty": 0,
       "function_call": "<function_call>"
     }'

MCP declares no tool for ai — tools/list on https://api.hanzo.ai/v1/mcp names the products it does reach. Use HTTP or an SDK.

AI API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousCreate chat — POST /v1/chat NextCreate decisions — POST /v1/decisions