Tokens API Reference

Easily integrate input token counts and costs into your apps and workflows. For free.

You need an account to get your API key.

Introduction

The API is designed around a RESTful approach. Our API has predictable, resource-oriented URLs, uses standard HTTP status codes and verbs, accepts JSON only for request bodies, and returns JSON only for all responses.

All API requests must be made over HTTPS. API calls made over plain HTTP are not supported.

While we will support multiple versions and backwards-compatibility in the future, currently there is only one version of the API, v1.

Base URL

https://api.zatomic.ai/v1

Authentication

An API key is required to authenticate all requests to the API. You can view and manage your API keys in your Zatomic account.

Authentication to the API is handled by either setting the X-Api-Key request header or by using the api-key querystring parameter. If both are given, the api-key querystring parameter will be used.

For authentication, API calls will fail for the following reasons:

Your API key not being sent in the request.
Your API key is invalid.

Authenticated Request

// With request header
curl -X GET https://api.zatomic.ai/v1/tokens/models \
  -H "X-Api-Key: {API key}"

// With querystring parameter
GET https://api.zatomic.ai/v1/tokens/models?api-key={API key}

Status Codes and Errors

Zatomic uses standard HTTP status codes to indicate success or failure of API requests. In general, 2xx codes represent success, 4xx codes indicate a bad request (such as an invalid API key), and 5xx codes mean something went wrong on our end (which should be rare).

HTTP Status Codes
200	OK	The request was successful.
400	Bad Request	The request was unacceptable.
401	Unauthorized	Invalid API key.
403	Forbidden	The API key doesn’t have permissions.
404	Not Found	The requested resource doesn't exist.
429	Too Many Requests	Too many requests hit the API too quickly, or you have surpassed your quota.
500	Internal Server Error	Something went wrong on Zatomic's end.

Error Response

{
   "status_code": 400,
   "title": "Bad Request",
   "message": "Authorization header not found.",
   "trace_id": "0HN7HFVHLU6LU:00000004",
   "event_id": null
}

Rate Limits and Quotas

The API currently has a rate limit of 10 requests per second and a quota limit of 5000 requests per month, per account. The quota limit resets on the 1st of every month.

If you exceed either of these limits, a 429 error code will be returned. You can inspect the following response headers for additional details pertaining to your rate and quota limits.

Response Headers for Rate/Quota Limits
X-Rate-Limit-Remaining-Calls	The number of remaining calls for the rate limit period, in seconds.
X-Rate-Limit-Total-Calls	The number of calls that can be made for the rate limit period, in seconds.
X-Rate-Limit-Retry-After	The amount of time left in the rate limit period until you can make more API calls, in seconds.
X-Quota-Limit-Retry-After	The amount of time left in the quota limit period until you can make more API calls, in seconds.

Too Many Requests Responses

// Rate limit exceeded
{
   "status_code": 429,
   "title": "Too Many Requests",
   "message": "Rate limit exceeded.",
   "trace_id": "928076d9668849ef8ccb8b42f0573662",
   "event_id": null
}

// Quota exceeded
{
   "status_code": 429,
   "title": "Too Many Requests",
   "message": "Quota exceeded.",
   "trace_id": "f548d0b906864d39ae4ab55ab3cbdf46",
   "event_id": null
}

Models

Use these endpoints to retrieve a list of AI models. You can get the list of all available models, the list of models by author, or you can get a single model by name.

Note that the endpoint to retrieve a single model still returns a list in the response, but it's just a list of one. This is to remain consistent with the other model endpoints.

Endpoints

GET https://api.zatomic.ai/v1/tokens/models
GET https://api.zatomic.ai/v1/tokens/models?author={author}
GET https://api.zatomic.ai/v1/tokens/models?name={name}

Response Properties
author string	The name of the company that produced the AI model.
name string	The unique identifying name of the AI model.
display_name string	The user-friendly display name of the AI model.
price_per_input_token decimal, nullable	The price per input token for the AI model, in USD.

Responses

// GET https://api.zatomic.ai/v1/tokens/models
[
   {
      "author": "AI21",
      "name": "jamba-1.5-large",
      "display_name": "Jamba 1.5 Large",
      "price_per_input_token": 0.000002
   },
   {
      "author": "AI21",
      "name": "jamba-1.5-mini",
      "display_name": "Jamba 1.5 Mini",
      "price_per_input_token": 0.0000002
   },
   {...},
   {...}
]

// GET https://api.zatomic.ai/v1/tokens/models?author=Meta
[
   {
      "author": "Meta",
      "name": "llama-2-7b",
      "display_name": "Llama 2 7B",
      "price_per_input_token": 0.00000052
   },
   {
      "author": "Meta",
      "name": "llama-2-7b-chat",
      "display_name": "Llama 2 7B Chat",
      "price_per_input_token": 0.00000052
   },
   {...},
   {...}
]

// GET https://api.zatomic.ai/v1/tokens/models?name=llama-3.2-1b
[
   {
      "author": "Meta",
      "name": "llama-3.2-1b",
      "display_name": "Llama 3.2 1B",
      "price_per_input_token": null
   }
]

Authors

Use this endpoint to retrieve the list of all available AI model authors.

You can then set the author querystring parameter in the model endpoints to retrieve the list of AI models for that author.

Endpoint

GET https://api.zatomic.ai/v1/tokens/authors

Response Properties
{string} string	The name of the company that produces an AI model.

Response

[
   "AI21",
   "Amazon",
   "Anthropic",
   "Cohere",
   "...",
   "..."
]

Token Counts

Use this endpoint to get the token count and cost for the submitted input.

Endpoint

POST https://api.zatomic.ai/v1/tokens/count

Request Properties
input string	The block of text for which to calculate the number of tokens and cost.
type string	The type of input being submitted. Currently the only accepted value is text.
models list of strings	The list of model names for which to calculate the token count and cost for the submitted input.

Request

{
   "input": "Felis nunc phasellus arcu ad bibendum elementum taciti.",
   "type": "text",
   "models": [
      "claude-2.1",
      "gemma-2-27b",
      "...",
      "..."
   ]
}

Response Properties
model string	The name of the AI model.
token_count integer, nullable	The number of tokens for the AI model for the submitted input.
token_cost decimal, nullable	The total cost of the tokens for the AI model for the submitted input, in USD.

Response

[
   {
      "model": "claude-2.1",
      "token_count": 18,
      "token_cost": 0.000144
   },
   {
      "model": "titan-text-lite-v1",
      "token_count": null,
      "token_cost": null
   },
   {...},
   {...}
]