Create a chat completion

POST

chat

completions

curl --request POST \
  --url https://api.nomask.ai/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "your-text-model-id",
  "messages": [
    {
      "role": "user",
      "content": "Explain a database index in one sentence."
    }
  ]
}
'

import requests

url = "https://api.nomask.ai/v1/chat/completions"

payload = {
    "model": "your-text-model-id",
    "messages": [
        {
            "role": "user",
            "content": "Explain a database index in one sentence."
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'your-text-model-id',
    messages: [{role: 'user', content: 'Explain a database index in one sentence.'}]
  })
};

fetch('https://api.nomask.ai/v1/chat/completions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1793617200,
  "model": "your-text-model-id",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A database index helps a database find matching rows without scanning the entire table."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 19,
    "total_tokens": 33
  },
  "nomask": {
    "cost_usd": 0.0001,
    "model_cost_usd": 0.0001,
    "prompt_cache": {
      "enabled": false,
      "usage_status": "unreported",
      "read_tokens": null,
      "write_tokens": null,
      "usd_per_1m_cached_input": null,
      "savings_usd": null
    }
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Create a NoMask API key at https://nomask.ai/api/keys. Keep it private; enter only your own key when sending a request.

Headers

Idempotency-Key

string

For non-streaming requests, identical key and body can replay a successful response for 24 hours. Streaming requests do not use this replay cache.

Body

application/json

OpenAI-compatible Chat Completions. Legacy functions/function_call, logprobs, audio, modalities, prediction, file inputs and web access fields are unsupported.

model

string

required

Current public text model ID from GET /models. No automatic OpenAI model-name mapping.

Minimum string length: 1

Example:

"your-text-model-id"

messages

object[]

required

Conversation history.

Minimum array length: 1

Show child attributes

stream

boolean

default:false

Return server-sent events rather than a completed JSON response.

stream_options

object

Show child attributes

temperature

number

Sampling temperature, subject to model support.

Required range: 0 <= x <= 2

top_p

number

Nucleus sampling probability, subject to model support.

Required range: 0 <= x <= 1

frequency_penalty

number

Frequency penalty, subject to model support.

Required range: -2 <= x <= 2

presence_penalty

number

Presence penalty, subject to model support.

Required range: -2 <= x <= 2

max_tokens

integer

Output token ceiling including reasoning. Defaults to model max_output_tokens; larger values are clamped to that ceiling.

Required range: x >= 1

max_completion_tokens

integer

Alias for max_tokens. Takes precedence when both are supplied.

Required range: x >= 1

stop

One stop sequence, or up to four.

enum<integer>

default:1

One completion per request.

Available options:

1

tools

object[]

Client-defined functions. Requires the model's function_calling capability. Your application executes returned tool calls.

Required array length: 1 - 64 elements

Show child attributes

tool_choice

Requires tools. Select automatically, prohibit tool calls, require a tool call, or name a function.

Available options:

auto,

none,

required

parallel_tool_calls

boolean

Allow multiple tool calls in one assistant turn. Used with tools.

reasoning

object

Show child attributes

reasoning_effort

enum<string>

Shorthand for reasoning effort; takes precedence over reasoning.effort. none requests Off.

Available options:

none,

minimal,

low,

medium,

high,

xhigh,

max

nomask_system_prompt

boolean

default:false

Prepend NoMask's model persona before your messages. Your own system messages are preserved.

response_format

object | null

Only text output is supported. Omit this field or set type=text. json_object and json_schema return unsupported_parameter.

Show child attributes

Response

Successful response. Example values are illustrative.

string

required

Completion identifier.

object

enum<string>

required

Available options:

chat.completion

created

integer<int64>

required

Unix timestamp.

model

string

required

Selected public model ID.

choices

object[]

required

Required array length: 1 element

Show child attributes

usage

object

required

Show child attributes

nomask

object

required

Show child attributes

Create a chat completion

curl --request POST \
  --url https://api.nomask.ai/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "your-text-model-id",
  "messages": [
    {
      "role": "user",
      "content": "Explain a database index in one sentence."
    }
  ]
}
'

import requests

url = "https://api.nomask.ai/v1/chat/completions"

payload = {
    "model": "your-text-model-id",
    "messages": [
        {
            "role": "user",
            "content": "Explain a database index in one sentence."
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'your-text-model-id',
    messages: [{role: 'user', content: 'Explain a database index in one sentence.'}]
  })
};

fetch('https://api.nomask.ai/v1/chat/completions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "created": 1793617200,
  "model": "your-text-model-id",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A database index helps a database find matching rows without scanning the entire table."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 19,
    "total_tokens": 33
  },
  "nomask": {
    "cost_usd": 0.0001,
    "model_cost_usd": 0.0001,
    "prompt_cache": {
      "enabled": false,
      "usage_status": "unreported",
      "read_tokens": null,
      "write_tokens": null,
      "usd_per_1m_cached_input": null,
      "savings_usd": null
    }
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

Docs

Getting Started

Text & Chat

Image

Production

Coding Tools

Chat API

Image API

Model API

Account & Usage

Errors & Limits

Create a chat completion

Authorizations

Headers

Body

Response