Text2Color API Documentation

Introduction

The Text2Color API allows you to convert text descriptions of colors in any language into their corresponding color codes. This API uses advanced language processing to interpret color descriptions and return accurate color representations in various formats including HEX, RGB and CMYK.

Base URL

All API requests should be made to:

https://api.text2color.com

Authentication

The API requires authentication for all requests. You need to include your API key in the header of each request.

API Key

To use the API, you need to include your API key in the X-API-Key header of each request:

X-API-Key: your_api_key_here

Obtaining an API Key

To obtain an API key, you need to register for an account. Once registered, you can generate API keys from your account dashboard.

Credit System

The API uses a credit system. Each API call consumes one credit from your account.

Initial Credits

New users receive 10 free credits upon registration.

Purchasing Credits

Additional credits can be purchased through our Stripe integration. The following credit packages are available:

1,000 credits - $1
10,000 credits - $10
100,000 credits - $100
1,000,000 credits - $1000

To purchase credits, login to your account.

Endpoints

Get Color from Description

GET /{format}/{color_description}

This endpoint takes a text description of a color and returns the corresponding color information in the specified format. This request requires authentication and consumes one credit. The maximum input is 100 characters.

Parameters

Name	Type	Description
format	string	The desired color format. Options: color (returns all), hex, rgb, cmyk
color_description	string	A text description of the desired color (e.g., "sky blue", "vibrant red", "mint green")

Response

The API returns a JSON object with the following structure:

{
  "color_description": "string",
  "format": "string",
  "value": "string or object (depending on format)"
}

Sample Requests

Request (COLOR):

GET https://api.text2color.com/color/sky%20blue

Response:

{
                    "color_description": "sky blue",
                    "cmyk": [
                    42,
                    12,
                    0,
                    7
                  ],
                    "hex_code": "#87ceeb",
                    "rgb": [
                      135,
                      206,
                      235
                    ]
                  }

Request (HEX):

GET https://api.text2color.com/hex/sky%20blue

Response:

{
  "color_description": "sky blue",
  "format": "hex",
  "value": "#87CEEB"
}

Request (RGB):

GET https://api.text2color.com/rgb/forest%20green

Response:

{
  "color_description": "forest green",
  "format": "rgb",
  "value": {
    "r": 34,
    "g": 139,
    "b": 34
  }
}

Request (CMYK):

GET https://api.text2color.com/cmyk/deep%20purple

Response:

{
  "color_description": "deep purple",
  "format": "cmyk",
  "value": {
    "c": 75,
    "m": 100,
    "y": 0,
    "k": 20
  }
}

Error Handling

In case of an error, the API will return an appropriate HTTP status code along with a JSON object containing an error message.

Example Error Responses

{
  "error": "Invalid color format specified"
}

{
  "error": "API key is missing"
}

{
  "error": "Invalid API key"
}

{
  "error": "Insufficient credits"
}

Best Practices

Use clear and concise color descriptions for best results.
Specify the desired color format to get the most relevant output for your needs.
Cache results when possible to reduce API calls and save credits.
Handle potential errors gracefully in your application.
Monitor your credit usage and purchase additional credits as needed.
Keep your API keys secure and do not share them publicly.

Interactive Console

Try out the API right here! Enter your API key, a color description, and select a format to see the result.

Support

If you encounter any issues or have questions about the API, please contact our support team at support@text2color.com