Skip to main content
The DeepMask API is OpenAI-compatible. You send chat requests to 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/generations return 404 with API_ENDPOINT_NOT_FOUND. SDK methods that rely on them don’t work, including the Responses API (client.responses) and client.models.retrieve().
  • Embeddings: the catalog has no embedding models, so client.embeddings.create() fails with an access error, usually 403 with API_MODEL_NOT_ALLOWED.
Paths are case-sensitive. A path with a trailing slash, such as /v1/chat/completions/, also returns 404.

Authentication

Send your API key as a bearer token in the Authorization 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 Authorization header. The Bearer prefix is case-sensitive.
  • A missing, malformed, unknown, or revoked key returns 401 with API_CREDENTIAL_INVALID.
To create or revoke keys, see API keys. The examples on this page read the key from the DEEPMASK_API_KEY environment variable.
Keep your API key on your server. Don’t put it in browser or mobile app code, where anyone who uses your app can read it. Browsers also block calls to the API from your own web pages (CORS), so call it from your backend.

Create a chat completion

This request sends a system message and a user message to gpt-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.
The response follows the OpenAI format. See Response for its fields.

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 a role 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", and text, 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_control on any part. See Unsupported parameters.
  • No developer role: use system instead.
  • name only on tool messages: remove name from system, user, and assistant messages.
  • Tool calls: an assistant message can include 1–128 tool calls. Each one has an id of 1–100 characters, type: "function", and a function object with name and arguments, a JSON string.
  • At least one user message: some models refuse a request that contains only a system message.
  • No message limit: you can send as many messages as fit in the model’s context window.
You can append the assistant message from a response to messages exactly as your SDK returns it. DeepMask accepts and removes the extra fields that SDKs and reasoning models add, such as empty refusal and annotations fields, and reasoning content. If refusal contains text, send your own assistant message instead.

Sampling options

Many SDKs, frameworks, and coding agents send sampling options with every request. DeepMask accepts temperature, 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 returns 400 with API_REQUEST_UNBOUNDED. Some models accept a narrower temperature range. 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 as 1.5 or "42" is refused. So is a value that doesn’t fit in a signed 64-bit integer. Very large seeds can lose precision, so keep seed within ±9,007,199,254,740,991 for exact results.
  • null means not set: DeepMask treats an option sent as null as if you left it out.
  • n only as 1: n: 1 is accepted because it’s the default. Any other value, such as 2 or 0, returns 400 with API_REQUEST_UNBOUNDED. To get several answers, send a separate request for each one.
  • stop as 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 without stop. gpt-4o, gpt-4.1, o3-mini, and mistral-large-3 receive them unchanged. The other models ignore stop. See Options that some models ignore.
  • Request size: stop counts 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.
  • temperature above 1: haiku-4.5, sonnet-4.5, opus-4.5, opus-4.6, and sonnet-4.6 accept temperature only from 0 to 1. So do deepseek-v3.2, glm-4.7, glm-4.7-flash, glm-5, kimi-k2.5, minimax-m2.1, minimax-m2.5, nemotron-3-super, and qwen3-235b-2507. The model provider refuses a higher value with a 4xx status and API_UPSTREAM_REJECTED. That refusal isn’t billed.
  • temperature on Claude 4.7 and later models: these models ignore temperature, 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_REJECTED and isn’t billed.

Unsupported parameters

These parameters and inputs return 400 with API_REQUEST_UNBOUNDED, unless the row names another code.
Some frameworks, agent libraries, and SDK wrappers add parameters such as reasoning_effort, top_k, logprobs, response_format, or an empty tools array, sometimes by default. DeepMask returns 400 with API_REQUEST_UNBOUNDED for those requests. Configure your tool so it doesn’t send these parameters, or call the API with the plain OpenAI SDK as shown on this page. Sampling options within their ranges are accepted, so you don’t need to remove them. On some models, keep temperature at 1 or below. See Sampling options.

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. Set max_tokens when you expect long answers.
  • GLM 4.7 models: glm-4.7 and glm-4.7-flash stop at 65,536 output tokens unless you set max_tokens.
  • Per-model maximum: each model accepts up to its own maximum, listed under Max output tokens in Models. A larger value returns 400 with API_REQUEST_UNBOUNDED.
  • Reasoning tokens count: for reasoning models such as o3-mini, and for the Claude models that always think, hidden reasoning tokens count toward max_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_reason is length. 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 413 with API_REQUEST_INVALID.
  • Uncompressed: send the body without compression. A body with a Content-Encoding header such as gzip, deflate, or br returns 400 with API_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, and stop together 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 returns 400 with API_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 429 with API_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 4xx status and API_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 400 with API_IMAGE_INPUT_UNSUPPORTED.
  • Not in the model list: GET /v1/models doesn’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.
The response has the same format as any other chat completion. See Response.

Image parts

An image part goes in the content 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", and image_url. Other keys, such as cache_control, are refused.
  • image_url keys: image_url is an object with url and an optional detail. Other keys, such as format, 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" and null, are refused. On gpt-4o and gpt-4.1, "low" uses far fewer tokens. The Claude models accept detail but ignore it.
  • User messages only: an image part in a system, assistant, or tool message is refused.
  • Images without text: a user message can contain image parts and no text part.
  • Chat Completions format: use image_url and text parts. Responses API parts are refused. For example, an input_image part with a base64 data URL returns API_IMAGE_INVALID, and an input_text part returns API_REQUEST_UNBOUNDED.

Image data

The url 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, or image/webp. Other formats, such as SVG, HEIC, BMP, or PDF, are refused.
  • JPEG label: image/jpg is also accepted. DeepMask sends it to the model as image/jpeg.
  • Matching type: the declared type must match the image bytes. For example, a JPEG file labeled image/png is 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 base64 on Linux wraps lines by default, so use base64 -w 0 or 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 400 with API_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 return 400 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, and detail: "high" still returns API_IMAGE_INVALID.
  • Find the cause: API_IMAGE_INVALID doesn’t say which rule failed. On macOS and Linux, file photo.png shows 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 own 4xx status or 502. 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 of prompt_tokens and are billed at the model’s Input rate. There’s no separate image price.
  • No separate count: usage doesn’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 on gpt-4o. A 512 × 512 pixel image used about 250 to 370 tokens.
  • detail: "low": on gpt-4o and gpt-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-4o and gpt-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_tokens in each response for the exact count.

Response

A successful request returns a chat completion object in the OpenAI format.
  • model is the API model ID you sent, such as gpt-4o.
  • choices[0].message holds the answer. When the model calls tools, content can be null and tool_calls lists the calls.
  • usage reports the input (prompt_tokens) and output (completion_tokens) tokens of the request.
Responses can include additional fields. Ignore any fields your app doesn’t use.

Finish reasons

The most common finish_reason values are:

Streaming

Set stream 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.
The response has the content type 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 usage object is sent only when you set include_usage to true. Its choices array can be empty, so check it before you read choices[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 error object instead of a chunk, for example data: {"error":{"message":"DeepMask API request could not be completed.","type":"api_error","code":"API_UPSTREAM_REJECTED"}}. Check each event for an error field.
  • 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 without data: [DONE] as incomplete. With the OpenAI SDKs, which hide [DONE], treat a stream with no chunk carrying a finish_reason as 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.
This example shows a full round trip with a get_weather function.
The first request returns a response like this one, shortened here. Copy its assistant message into the second request, and use each call’s id as tool_call_id.
Send the same tools array with every request in a tool-calling conversation. Some models refuse a request whose history contains tool calls when tools is missing.

Tool choice

tool_choice controls whether and how the model uses your tools. It requires tools.

Model-specific tool restrictions

Every model supports tools 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, and opus-5.5 don’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 a description. Without one, the provider refuses the request with 422 and API_UPSTREAM_REJECTED. That refusal isn’t billed.
If a model can’t apply one of your tool settings, DeepMask refuses the request instead of running it without that setting.

Tool definition rules

  • Each entry in tools has exactly two keys: type, set to "function", and function.
  • function can contain name, description, parameters, and strict. Other keys are refused.
  • name is 1–64 characters: letters, digits, underscores, and hyphens.
  • description is a string.
  • parameters is a JSON Schema object. It can be nested up to 32 levels deep, and every number must be finite.
  • strict is a boolean.
  • 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 $ref can’t contain $id below its root (or a root $id with a # fragment), $anchor, $dynamicRef, $dynamicAnchor, $recursiveRef, or $recursiveAnchor. It also can’t declare a draft-03 or draft-04 $schema.
  • A property literally named $ref or $id is refused.
  • After its references are resolved, a tool’s schema can be at most about 32 times the size of your tools array as sent and at most 64 levels deep. Messages, the resolved tools, tool_choice, and stop must 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, and mistral-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.
  • created is always 0 and owned_by is always deepmask.
  • Retrieving a single model with GET /v1/models/{id} isn’t supported and returns 404.
Listing models isn’t billed. Use Models to compare context windows and prices.

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. The message 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.

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.