POST /v1/chat/completions, and you list the models your key can use with GET /v1/models. Because the API follows the OpenAI format, you can use the official OpenAI SDKs by changing only the base URL and the API key.
DeepMask accepts a defined subset of the OpenAI parameters. A request with an unsupported parameter is refused instead of running without it. Some models ignore some sampling options, such as top_p or seed, without an error. See Sampling options. To make your first call, start with the Quickstart.
You need an API key created by an organization admin. Your organization also needs an active Pro, Power, or Enterprise plan with API billing enabled.
The base URL is
https://api.deepmask.io/v1. Organization admins can also copy it from Base URL in User Settings > API.Endpoints
Only these two endpoints are available. Other OpenAI endpoints, including embeddings and image generation, aren’t offered.
- Most other endpoints: paths such as
/v1/responses,/v1/completions, and/v1/images/generationsreturn404withAPI_ENDPOINT_NOT_FOUND. SDK methods that rely on them don’t work, including the Responses API (client.responses) andclient.models.retrieve(). - Embeddings: the catalog has no embedding models, so
client.embeddings.create()fails with an access error, usually403withAPI_MODEL_NOT_ALLOWED.
/v1/chat/completions/, also returns 404.
Authentication
Send your API key as a bearer token in theAuthorization header of every request. POST requests also need a JSON content type.
- Keys start with
sk-, followed by 64 lowercase hexadecimal characters. - Send exactly one
Authorizationheader. TheBearerprefix is case-sensitive. - A missing, malformed, unknown, or revoked key returns
401withAPI_CREDENTIAL_INVALID.
DEEPMASK_API_KEY environment variable.
Create a chat completion
This request sends a system message and a user message togpt-4o. The Python and Node.js examples use the official openai package. Install it with pip install openai or npm install openai. The Node.js examples use ES modules, so save them as .mjs files or set "type": "module" in package.json.
Request body
The last seven fields are sampling options. You can send any of them as
null, which means not set. Some models ignore some of them. See Sampling options.
Any other top-level field returns 400 with API_REQUEST_UNBOUNDED. A field with the wrong type or a value outside its limits returns the same error. There are three exceptions, which return 400 with API_REQUEST_INVALID: a missing or non-string model, a user value that contains NUL, and a string that contains invalid Unicode.
Organization admins can copy each model’s ID from API model ID on the Models tab in User Settings > API. If you can’t open that page, call GET /v1/models with your key to list the model IDs it can use. A model that isn’t assigned to your key returns 403 with API_MODEL_NOT_ALLOWED. You can’t add models to an existing key, so create a new key to use other models. See Models for the catalog.
Messages
Each message has arole and content. System and user messages can send content as a string or as an array of content parts.
- Text parts: a text part has exactly two keys:
type, set to"text", andtext, a string. Text parts work on every model. - Content arrays: an array holds 1–256 parts. An empty array is refused.
- Images: image parts work only in user messages, and only on the seven models listed under Image input. Other models refuse them, even if they accept images in DeepMask Chat.
- No other content: file, audio, and document parts are refused. So is
cache_controlon any part. See Unsupported parameters. - No
developerrole: usesysteminstead. nameonly on tool messages: removenamefrom system, user, and assistant messages.- Tool calls: an assistant message can include 1–128 tool calls. Each one has an
idof 1–100 characters,type: "function", and afunctionobject withnameandarguments, a JSON string. - At least one user message: some models refuse a request that contains only a
systemmessage. - No message limit: you can send as many messages as fit in the model’s context window.
Sampling options
Many SDKs, frameworks, and coding agents send sampling options with every request. DeepMask acceptstemperature, top_p, presence_penalty, frequency_penalty, seed, stop, and n. See Request body for the type and range of each one.
- Ranges: each range includes its end values, so DeepMask accepts
temperature: 2. A value outside its range returns400withAPI_REQUEST_UNBOUNDED. Some models accept a narrowertemperaturerange. See Options that some models ignore. - Numbers only: send numbers as JSON numbers. A string such as
"0.5"or a boolean is refused. - Whole numbers for
seed: a value such as1.5or"42"is refused. So is a value that doesn’t fit in a signed 64-bit integer. Very large seeds can lose precision, so keepseedwithin ±9,007,199,254,740,991 for exact results. nullmeans not set: DeepMask treats an option sent asnullas if you left it out.nonly as 1:n: 1is accepted because it’s the default. Any other value, such as2or0, returns400withAPI_REQUEST_UNBOUNDED. To get several answers, send a separate request for each one.stopas a string or an array: a string counts as one stop sequence. An array can hold 1 to 4 strings. An empty array or an array with more than 4 strings is refused.- No empty stop sequences: an empty string (
"") is refused, on its own or in an array. - Blank stop sequences: on the Claude models, DeepMask removes stop sequences that contain only whitespace, such as
"\n\n". If no sequence is left, the request runs withoutstop.gpt-4o,gpt-4.1,o3-mini, andmistral-large-3receive them unchanged. The other models ignorestop. See Options that some models ignore. - Request size:
stopcounts toward the 32 MiB limit for messages and tools. See Request size.
Options that some models ignore
Not every model supports every sampling option. When a model doesn’t support an option, DeepMask accepts it but doesn’t send it to the model. The option then has no effect. You get no error, and you’re billed as if you hadn’t sent it.temperatureabove 1:haiku-4.5,sonnet-4.5,opus-4.5,opus-4.6, andsonnet-4.6accepttemperatureonly from 0 to 1. So dodeepseek-v3.2,glm-4.7,glm-4.7-flash,glm-5,kimi-k2.5,minimax-m2.1,minimax-m2.5,nemotron-3-super, andqwen3-235b-2507. The model provider refuses a higher value with a4xxstatus andAPI_UPSTREAM_REJECTED. That refusal isn’t billed.temperatureon Claude 4.7 and later models: these models ignoretemperature, as the table shows. A value above 1 therefore has no effect on them.- Other provider refusals: a model provider can also refuse a value that its model doesn’t support. That refusal also returns
API_UPSTREAM_REJECTEDand isn’t billed.
Unsupported parameters
These parameters and inputs return400 with API_REQUEST_UNBOUNDED, unless the row names another code.
Output length
max_tokens sets the maximum number of output tokens for a response. max_completion_tokens works the same way. Send only one of them. For all token limits in one place, see Token limits.
- No DeepMask default for most models: if you omit
max_tokens, DeepMask adds no limit of its own. The model’s default output length applies, and it can be lower than the model’s maximum. Setmax_tokenswhen you expect long answers. - GLM 4.7 models:
glm-4.7andglm-4.7-flashstop at 65,536 output tokens unless you setmax_tokens. - Per-model maximum: each model accepts up to its own maximum, listed under Max output tokens in Models. A larger value returns
400withAPI_REQUEST_UNBOUNDED. - Reasoning tokens count: for reasoning models such as
o3-mini, and for the Claude models that always think, hidden reasoning tokens count towardmax_tokens. They’re billed as output tokens. You can’t turn thinking off for these Claude models. See Reasoning and thinking tokens for which models always think. - Truncated answers: when an answer reaches the limit,
finish_reasonislength. With a low limit, reasoning can use up the budget before the visible answer is complete. - Long requests: a request can run for up to 15 minutes. The OpenAI SDKs time out after 10 minutes by default and then retry, and DeepMask bills both requests. For long answers, raise the client
timeout. See Retries in the OpenAI SDKs. - At the 15-minute limit: DeepMask stops the request. Its outcome is then unclear, so it isn’t billed unless usage for it still arrives later. See Request duration.
Request size
For all size and duration limits in one place, see Request size and duration.- Body: a request body can be up to 32 MiB. A larger body returns
413withAPI_REQUEST_INVALID. - Uncompressed: send the body without compression. A body with a
Content-Encodingheader such asgzip,deflate, orbrreturns400withAPI_REQUEST_INVALID. The OpenAI SDKs send uncompressed bodies. - Base64 images: the base64 text of your images counts toward the 32 MiB. 20 MB of images is about 26.7 MB of base64, which leaves about 6.9 MB for the rest of the request.
- Messages, tools, and stop sequences: messages, tool definitions,
tool_choice, andstoptogether can be up to 32 MiB as UTF-8 JSON. Base64 images count here too. Tool schemas count with their$refs resolved. Above that, the request returns400withAPI_REQUEST_UNBOUNDED. - Bodies in flight: the request bodies that one key has in flight can total up to 64 MiB. A request that would go over returns
429withAPI_CONCURRENCY_LIMIT. With large images, send fewer requests in parallel. See Per-key requests in flight. - Context window: in practice, the model’s context window is the limit. A prompt that doesn’t fit is refused by the model provider with a
4xxstatus andAPI_UPSTREAM_REJECTED. That refusal isn’t billed. See Models for each model’s context window.
Image input
You can send images in user messages to seven models:gpt-4o, gpt-4.1, and the Claude models haiku-4.5, sonnet-4.5, opus-4.5, opus-4.6, and sonnet-4.6. The model reads the images together with your text and answers in text. The same list is in Image input on the Models page.
- Base64 only: you send each image inside the request as a base64 data URL. DeepMask refuses image links and never downloads them.
- Other models refuse images: a valid image part sent to any other model returns
400withAPI_IMAGE_INPUT_UNSUPPORTED. - Not in the model list:
GET /v1/modelsdoesn’t show which models accept images.
Send an image
This example sends a local PNG file,photo.png, with a question to gpt-4o. For another format, change image/png in the data URL to match the file. The cURL example writes the request to a file first, because a large image doesn’t fit in a single command-line argument.
Image parts
An image part goes in thecontent array of a user message. You can combine image parts and text parts in any order.
- Part keys: an image part has exactly two keys:
type, set to"image_url", andimage_url. Other keys, such ascache_control, are refused. image_urlkeys:image_urlis an object withurland an optionaldetail. Other keys, such asformat, are refused. A string in place of the object is also refused.detail: leave it out, or set it to"auto"or"low". Other values, including"high"andnull, are refused. Ongpt-4oandgpt-4.1,"low"uses far fewer tokens. The Claude models acceptdetailbut ignore it.- User messages only: an image part in a
system,assistant, ortoolmessage is refused. - Images without text: a user message can contain image parts and no text part.
- Chat Completions format: use
image_urlandtextparts. Responses API parts are refused. For example, aninput_imagepart with a base64 data URL returnsAPI_IMAGE_INVALID, and aninput_textpart returnsAPI_REQUEST_UNBOUNDED.
Image data
Theurl must be a data URL in the form data:image/<type>;base64,<data>. Nothing else can appear before the comma.
- Formats: PNG, JPEG, GIF, and WebP. Write the type in lowercase:
image/png,image/jpeg,image/gif, orimage/webp. Other formats, such as SVG, HEIC, BMP, or PDF, are refused. - JPEG label:
image/jpgis also accepted. DeepMask sends it to the model asimage/jpeg. - Matching type: the declared type must match the image bytes. For example, a JPEG file labeled
image/pngis refused. - Standard base64: use the standard alphabet (
A–Z,a–z,0–9,+, and/) with=padding. URL-safe base64, which uses-and_, is refused. So is base64 without its padding. - One line: line breaks in the base64 are refused. GNU
base64on Linux wraps lines by default, so usebase64 -w 0or remove the line breaks. - Animated images: animated WebP images are refused. Animated GIFs are accepted, but every frame must fit within the pixel limit. A model provider can refuse a GIF it can’t read, so send still images when you can.
- No links:
https://,http://, and other URLs are refused. DeepMask doesn’t download them.
Image limits
These limits apply to each request. The count and the total size include the images in every message, including earlier turns of the conversation.- Decoded size: sizes are of the decoded image, not of the base64 text. 1 MB is 1,000,000 bytes.
- Pixels: each side of an image must be from 1 to 8,000 pixels.
- Over a limit: the request returns
400withAPI_IMAGE_INVALID. - Large photos: phone photos can be larger than 3.75 MB, and some phones save them as HEIC. Before you encode a photo, save it as JPEG with its longest side at about 2,000 pixels. The model provider scales large images down anyway, so the model sees about the same detail.
- Long conversations: to stay within the limits, remove images from earlier turns that the model no longer needs.
- Request body: the base64 text also counts toward the 32 MiB request body. See Request size.
Image errors
Image refusals return400 before the request reaches the model, so you aren’t billed for them.
- Image checks come first: DeepMask checks the shape of each image part before it checks whether the model accepts images. On a model without image input, a link still returns
API_IMAGE_URL_UNSUPPORTED, anddetail: "high"still returnsAPI_IMAGE_INVALID. - Find the cause:
API_IMAGE_INVALIDdoesn’t say which rule failed. On macOS and Linux,file photo.pngshows the real format of the file and its size in pixels. Compare them with the type in the data URL and with the image limits. - Other parts: a request that also contains a file, audio, or document part returns
API_REQUEST_UNBOUNDED. - Provider refusals: if the model provider can’t process an image that passed these checks, the request fails with
API_UPSTREAM_REJECTED. Depending on the model, the status is the provider’s own4xxstatus or502. You aren’t billed for it. Check the image, for example by converting it to PNG, instead of retrying it unchanged. See Provider errors.
How images are billed
Images are billed as input tokens. Image tokens are part ofprompt_tokens and are billed at the model’s Input rate. There’s no separate image price.
- No separate count:
usagedoesn’t report image tokens or the number of images. - Tokens per image: the count depends on the image size and the model. In DeepMask’s measurements, a large image used up to about 1,500 tokens on the Claude models, about 1,450 on
gpt-4.1, and about 1,700 ongpt-4o. A 512 × 512 pixel image used about 250 to 370 tokens. detail: "low": ongpt-4oandgpt-4.1, an image with"low"used about 85 to 105 tokens.- Large images are scaled down: the model provider scales large images down before the model reads them. An 8,000 × 8,000 pixel image cost no more tokens than the large images above.
- Many images: at about 1,700 tokens each, 20 large images add about 34,000 input tokens.
- Repeated images: on
gpt-4oandgpt-4.1, an image that repeats in later requests can be billed at the cached input rate. See Cached input. - Exact counts: provider token rules can change. Read
usage.prompt_tokensin each response for the exact count.
Response
A successful request returns a chat completion object in the OpenAI format.modelis the API model ID you sent, such asgpt-4o.choices[0].messageholds the answer. When the model calls tools,contentcan benullandtool_callslists the calls.usagereports the input (prompt_tokens) and output (completion_tokens) tokens of the request.
Finish reasons
The most commonfinish_reason values are:
Streaming
Setstream to true to receive the answer as server-sent events while the model writes it. Add stream_options: {"include_usage": true} to also receive the token counts.
text/event-stream. Each event is a data: line with a chat completion chunk, and the stream ends with data: [DONE]. A shortened stream looks like this:
- Events arrive as they’re ready: DeepMask forwards each event as soon as it’s complete.
- Empty chunks are left out: every chunk you receive has at least one choice. The only exception is the usage chunk.
- Usage on request: the final chunk with a
usageobject is sent only when you setinclude_usagetotrue. Itschoicesarray can be empty, so check it before you readchoices[0]. - Errors before the stream starts: if a streaming request is refused before the first chunk, you get a normal JSON error with an HTTP error status.
- Errors during the stream: if an error happens after the stream has started, you receive an event with an
errorobject instead of a chunk, for exampledata: {"error":{"message":"DeepMask API request could not be completed.","type":"api_error","code":"API_UPSTREAM_REJECTED"}}. Check each event for anerrorfield. - Streams that stop early: if a request reaches the 15-minute request limit, or the connection fails on DeepMask’s side, the stream closes without an error event and without
data: [DONE]. With raw HTTP, treat a stream that ends withoutdata: [DONE]as incomplete. With the OpenAI SDKs, which hide[DONE], treat a stream with no chunk carrying afinish_reasonas incomplete. See Errors in streamed responses. - Unclear outcome: a stream that ends with an error event or stops early on DeepMask’s or the provider’s side has an unclear outcome. It isn’t billed unless usage for it still arrives later. More than 20 unclear outcomes in any 24 hours pause your organization’s requests. See Unclear outcomes.
If your client disconnects during a stream, the request still runs to completion and is billed. To limit what an abandoned response can cost, set
max_tokens.Tool calling
Tool calling lets the model ask your app to run a function, such as looking up data. The model never runs the function itself. Your code runs it and sends the result back.1
Send your tools
Add
tools to your request. Each tool is a function with a name, a description, and a JSON Schema in parameters.2
Check for tool calls
When the model wants to use a tool,
finish_reason is tool_calls and message.tool_calls lists the calls. Each call has an id, the function name, and its arguments as a JSON string.3
Run the functions
Parse the arguments and run the matching function in your code.
4
Send the results
Append the assistant message and one
tool message per call, with the call’s id as tool_call_id. Send the request again with the same tools. Repeat until finish_reason is stop.get_weather function.
message into the second request, and use each call’s id as tool_call_id.
Tool choice
tool_choice controls whether and how the model uses your tools. It requires tools.
Model-specific tool restrictions
Every model supportstools with tool_choice: "auto". Some models don’t support every other tool option. A request that uses an unsupported option returns 400 with API_REQUEST_UNBOUNDED before it reaches the model, so it isn’t billed.
parallel_tool_calls: on models marked No, the request is refused when the field is present, whatever its value. Leave it out.- Forced tool choice:
sonnet-5,sonnet-5.5, andopus-5.5don’t accept"required"or a named function. Use"auto", and describe in your prompt when the model should use a tool. mistral-large-3: give every function adescription. Without one, the provider refuses the request with422andAPI_UPSTREAM_REJECTED. That refusal isn’t billed.
Tool definition rules
Function definitions
Function definitions
- Each entry in
toolshas exactly two keys:type, set to"function", andfunction. functioncan containname,description,parameters, andstrict. Other keys are refused.nameis 1–64 characters: letters, digits, underscores, and hyphens.descriptionis a string.parametersis a JSON Schema object. It can be nested up to 32 levels deep, and every number must be finite.strictis a boolean.
Schemas with $ref
Schemas with $ref
- Only local references work:
#,#/$defs/name,#/definitions/name, or another JSON pointer inside the same schema. - Remote references and pointers with an escaped slash (
%2F) are refused. - A schema that uses
$refcan’t contain$idbelow its root (or a root$idwith a#fragment),$anchor,$dynamicRef,$dynamicAnchor,$recursiveRef, or$recursiveAnchor. It also can’t declare a draft-03 or draft-04$schema. - A property literally named
$refor$idis refused. - After its references are resolved, a tool’s schema can be at most about 32 times the size of your
toolsarray as sent and at most 64 levels deep. Messages, the resolved tools,tool_choice, andstopmust still fit in 32 MiB together. - Recursive schemas, where a reference points back to a schema that contains it, work only on
gpt-4o,gpt-4.1,gpt-5.4,o3-mini, andmistral-large-3.
List models
GET /v1/models returns the models your API key can use. It uses the same authentication as chat requests.
- The list contains only the models assigned to the key, sorted by ID.
- A model that DeepMask removes from the catalog disappears from the list, even if it was assigned to the key.
- Models that DeepMask adds later aren’t added to existing keys.
createdis always0andowned_byis alwaysdeepmask.- Retrieving a single model with
GET /v1/models/{id}isn’t supported and returns404.
What you’re billed for
You pay for the input and output tokens each request uses, including images, tool definitions, tool calls, tool results, and hidden reasoning tokens. For how images are counted, see How images are billed. See How pricing works for rates, cached input, and long-prompt pricing. A request has an unclear outcome when DeepMask can’t tell whether it finished. Examples are a server error or timeout at the model provider, a stream that breaks off midway, and a request that reaches the 15-minute limit. DeepMask doesn’t charge for these requests. On its own, an unclear outcome doesn’t pause your organization’s requests. If usage for such a request still arrives later, DeepMask bills that usage like any other usage. More than 20 unclear outcomes in any 24 hours pause your organization’s requests until DeepMask resolves them. See Unclear outcomes. For which refused and interrupted requests are billed, see Are failed requests billed?.Common request errors
Errors from these endpoints share one JSON shape. Themessage never changes, so handle errors by the HTTP status and error.code.
For authentication, billing, rate limit, and spending cap errors, see Errors and retries. For rate, token, and budget limits, see Limits and fair use.
Related pages
Quickstart
Create a key and make your first request.
Models
Browse model IDs, context windows, and pricing.
API keys
Create keys, choose their models, and revoke them.
Limits and fair use
See the rate, token, and budget limits that apply to your requests.
Errors and retries
Handle every error code and learn which errors to retry.