Name: RedBTC AI Gateway: OpenAI-Compatible API with Capped Billing
Brand: tokenmax
SKU: api-tokenmax-redbtc-ai-gateway
Availability: InStock
Author: API Market

# RedBTC AI Gateway API

## Overview
The RedBTC AI Gateway API provides a robust, OpenAI-compatible `/v1/chat/completions` interface, enabling developers, agents, and automation tools to integrate advanced large language model capabilities into their applications. Designed for cost-efficiency and predictability, the API offers low-cost token-credit plans with hard caps, ensuring no surprise overage charges. It acts as a versatile gateway, supporting various GPT-style models and facilitating multi-model routing for diverse AI-powered solutions.

## Features
*   **OpenAI-compatible Interface**: Seamless integration with existing tools and libraries designed for OpenAI's `/v1/chat/completions` endpoint.
*   **Cost-Effective Token Credits**: Transparent, low-cost billing based on token usage, with distinct rates for input and output tokens.
*   **Hard-Capped Plans**: Predictable spending with no overage charges, making it safe for testing, development, and production workloads.
*   **Multi-Model Routing**: Access to a range of GPT-style models through a unified gateway (specific models available via `/v1/models`).
*   **Synchronous Processing**: Immediate response for chat completions, simplifying integration without the need for polling or status checks.
*   **Comprehensive Billing Transparency**: Detailed `X-Magicapi-Billing` header in responses provides exact credit usage for each request.

## Use Cases
*   **Automated Customer Support (Customer Service Automation)**: Integrate the API into chatbots and virtual assistants to provide instant, AI-driven responses to customer inquiries, improving service efficiency and availability 24/7.
*   **Content Generation and Curation (Digital Marketing & Content Creation)**: Generate marketing copy, blog posts, social media updates, and product descriptions at scale. Developers can automate content pipelines, ensuring fresh and relevant material for various platforms.
*   **Code Assistance and Generation (Software Development)**: Empower developers with an AI assistant that can generate code snippets, explain complex functions, debug code, or convert code between languages, significantly accelerating the development cycle.
*   **Data Analysis and Summarization (Business Intelligence)**: Process large volumes of text data from reports, articles, or internal documents to extract key insights, summarize content, or answer specific questions, aiding in faster decision-making.
*   **Educational Content Creation (EdTech)**: Develop interactive learning tools that can explain complex topics, generate quizzes, or provide personalized tutoring experiences based on user input, making education more accessible and engaging.

## API Documentation

### Base URL
All API requests should be made to: `https://prod.api.market/api/v1/tokenmax/redbtc-ai-gateway`

### Authentication
Authentication is handled via API key. Include your API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```
Replace `YOUR_API_MARKET_KEY` with your actual API.market key.

### Endpoints

#### `GET /health`
Performs a health check on the API Gateway. This endpoint verifies the service's operational status.

**Summary:** Health check
**Operation ID:** `health`
**Authentication:** Required (`x-api-market-key`)

**Request Example:**
```bash
curl -X GET "https://prod.api.market/api/v1/tokenmax/redbtc-ai-gateway/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Example (200 OK):**
```json
{
  "ok": true
}
```

#### `GET /v1/models`
Lists the available OpenAI-compatible models accessible through the RedBTC AI Gateway.

**Summary:** List available OpenAI-compatible models
**Operation ID:** `listModels`
**Authentication:** Required (`x-api-market-key`)

**Request Example:**
```bash
curl -X GET "https://prod.api.market/api/v1/tokenmax/redbtc-ai-gateway/v1/models" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response Example (200 OK):**
```json
{
  "data": [
    {
      "id": "gpt-5.4-mini",
      "object": "model",
      "created": 1677610000,
      "owned_by": "RedBTC",
      "permission": [
        {
          "id": "modelperm-xxxx",
          "object": "model_permission",
          "created": 1677610000,
          "allow_create_engine": false,
          "allow_sample_finetuning": false,
          "allow_logprobs": false,
          "allow_search_indices": false,
          "allow_view": true,
          "allow_fine_tuning": false,
          "organization": "*",
          "group": null,
          "is_blocking": false
        }
      ],
      "root": "gpt-5.4-mini",
      "parent": null
    },
    {
      "id": "redbtc-coding-v1",
      "object": "model",
      "created": 1677610001,
      "owned_by": "RedBTC",
      "permission": [
        {
          "id": "modelperm-yyyy",
          "object": "model_permission",
          "created": 1677610001,
          "allow_create_engine": false,
          "allow_sample_finetuning": false,
          "allow_logprobs": false,
          "allow_search_indices": false,
          "allow_view": true,
          "allow_fine_tuning": false,
          "organization": "*",
          "group": null,
          "is_blocking": false
        }
      ],
      "root": "redbtc-coding-v1",
      "parent": null
    }
  ],
  "object": "list"
}
```
*Note: The actual list of models may vary.*



#### `POST /v1/chat/completions`
Creates a chat completion given the provided messages. This endpoint is fully compatible with the OpenAI chat completions API specification.

**Summary:** Create chat completion
**Operation ID:** `createChatCompletion`
**Authentication:** Required (`x-api-market-key`)

**Request Body:**
*   `model` (string, required): ID of the model to use. Example: `"gpt-5.4-mini"`.
*   `messages` (array, required): A list of messages comprising the conversation so far.
    *   Each message object must contain:
        *   `role` (string, required): The role of the author of this message. Enum: `system`, `user`, `assistant`, `tool`.
        *   `content` (string or array, required): The contents of the message.
*   `max_tokens` (integer, optional, default: `1200`, maximum: `1200`): The maximum number of tokens to generate in the chat completion.
*   `temperature` (number, optional, default: `1.0`, minimum: `0`, maximum: `2`): What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
*   `stream` (boolean, optional): If set to `true`, partial message deltas will be sent, but this is **forced to `false` by the gateway for marketplace metering safety** on this channel. Therefore, only a complete response will be returned.

**Request Example:**
```bash
curl -X POST "https://prod.api.market/api/v1/tokenmax/redbtc-ai-gateway/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Tell me a fun fact about giraffes."}
    ],
    "max_tokens": 100,
    "temperature": 0.7
  }'
```

**Response Example (200 OK):**
```json
{
  "id": "chatcmpl-12345",
  "object": "chat.completion",
  "created": 1677649200,
  "model": "gpt-5.4-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Giraffes have the same number of neck vertebrae as humans – just seven! Each one is just super elongated."
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 23,
    "total_tokens": 41
  }
}
```

## Status Codes
A comprehensive list of HTTP status codes and their meanings:

*   **`200 OK`**: The request was successful, and the response body contains the requested data.
*   **`400 Bad Request`**: The request was malformed, or the input parameters were invalid. Review your request body and parameters against the API schema.
*   **`401 Unauthorized`**: The `x-api-market-key` header is missing or invalid. Ensure you are providing a valid API key.
*   **`403 Forbidden`**: Your API key is valid, but you do not have sufficient permissions to access the requested resource or perform the action. This might indicate plan limitations or account restrictions.
*   **`404 Not Found`**: The requested resource could not be found. This typically happens if an endpoint path is incorrect.
*   **`429 Too Many Requests`**: You have exceeded the rate limit, concurrency limit, or daily unit limit for your plan. Slow down your requests or contact support for a higher limit.
*   **`500 Internal Server Error`**: A general server-side error occurred. This is typically not due to your request and should be reported if it persists.
*   **`503 Service Unavailable`**: The service is temporarily unavailable, usually due to maintenance or high load. You should implement a retry mechanism for these errors.

## Rate Limits
The RedBTC AI Gateway API implements rate limiting to ensure fair usage and protect the service. If you exceed the allocated request rate or concurrency limits for your plan, you will receive a `429 Too Many Requests` HTTP status code. Details on specific rate limits are tied to your subscription plan. For high-volume use cases, contact API.market support to discuss increased limits.

## Error Handling
Effective error handling is crucial for robust API integrations. The RedBTC AI Gateway API provides informative error responses to help you diagnose and resolve issues.

*   **Interpreting Error Responses**: When an error occurs (e.g., `4xx` or `5xx` status codes), the response body will typically contain a JSON object providing more details.
*   **Common Errors and Resolution**:
    *   **`400 Bad Request`**:
        *   **Issue**: Malformed JSON, missing required parameters (`model`, `messages`), or parameters outside valid ranges (`max_tokens`, `temperature`).
        *   **Resolution**: Validate your request payload against the OpenAPI schema.
    *   **`401 Unauthorized`**:
        *   **Issue**: Missing or incorrect `x-api-market-key` header.
        *   **Resolution**: Ensure your API key is correctly included in the `x-api-market-key` header.
    *   **`429 Too Many Requests`**:
        *   **Issue**: Exceeded your plan's rate, concurrency, or usage limits.
        *   **Resolution**: Implement exponential backoff retry logic. If the issue persists, review your usage patterns or consider upgrading your plan.
*   **Retry Strategies**: For transient errors (e.g., `500 Internal Server Error`, `503 Service Unavailable`, `429 Too Many Requests`), implement an exponential backoff strategy:
    1.  Wait for an initial short delay (e.g., 0.5 - 1 second).
    2.  If the error persists, double the delay for the next retry.
    3.  Add a small random jitter to the delay to prevent thundering herd problems.
    4.  Set a maximum number of retries or a total timeout to prevent indefinite waiting.

**Error Response Example:**
```json
{
  "error": {
    "code": "invalid_request_error",
    "message": "The 'model' parameter is required for chat completions.",
    "type": "invalid_request_error",
    "param": "model",
    "status": 400
  }
}
```



## cURL
This example shows a direct cURL command for a synchronous chat completion request.

```bash
# cURL example for synchronous request
curl -X POST "https://prod.api.market/api/v1/tokenmax/redbtc-ai-gateway/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "max_tokens": 50,
    "temperature": 0.5
  }'
```

### Performance Optimization
To optimize your usage and minimize costs with the RedBTC AI Gateway API:

*   **Optimize Prompt Engineering**: Craft concise and effective prompts. Longer input messages consume more input tokens, leading to higher costs. Aim for clarity and directness.
*   **Adjust `max_tokens` Appropriately**: Set `max_tokens` to the minimum required for your desired output. Generating unnecessary output tokens directly increases costs (output tokens are 4x more expensive than input tokens).
*   **Utilize System Messages**: Leverage the `system` role to set the context, persona, or guidelines for the AI, which can help guide its responses more effectively without excessively long user prompts.
*   **Cache Frequent Responses**: For common queries with predictable answers, consider caching the API responses locally to reduce redundant calls and token usage.
*   **Monitor `X-Magicapi-Billing` Header**: Regularly inspect the `X-Magicapi-Billing` header in your responses to track token usage and ensure your application is operating within expected cost parameters.
*   **Implement Retry with Backoff**: For transient errors (`429`, `500`, `503`), implement an exponential backoff strategy to manage rate limits and ensure successful processing without overloading the API.

## FAQ

**Q: What is the RedBTC AI Gateway API?**

A: It's an OpenAI-compatible API that provides access to GPT-style large language models, designed for developers and automation, with transparent token-based billing and hard-capped plans.

**Q: Is the API compatible with OpenAI's API?**

A: Yes, it provides an OpenAI-compatible `/v1/chat/completions` interface, allowing for easy integration with existing tools and libraries.

**Q: How is billing handled?**

A: Billing is based on token credits. Input tokens cost 1 credit each, and output tokens cost 4 credits each. Health checks and error requests are free. Plans are hard-capped to prevent overage charges.

**Q: What does "hard-capped" mean?**

A: It means your usage will never exceed the credits available in your plan. Once your credits are used, further requests will fail until your plan renews or is topped up, ensuring no surprise bills.

**Q: Can I stream responses?**

A: Streaming is currently disabled on this marketplace channel to ensure stable and accurate metering for billing purposes. All responses are returned in full.

**Q: How do I handle errors and rate limits?**

A: The API returns standard HTTP status codes (e.g., `400`, `401`, `429`, `500`). For `429 Too Many Requests` or transient server errors, implement an exponential backoff retry strategy. Detailed error messages are provided in JSON format.

**Q: Which models are available through the gateway?**

A: You can discover the currently available models by calling the `GET /v1/models` endpoint. These are typically GPT-style models optimized for various tasks.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Access RedBTC AI Gateway, an OpenAI-compatible API with low-cost, hard-capped token credit plans. Ideal for developers, agents, and automation tools seeking pre

RedBTC AI Gateway: OpenAI-Compatible API with Capped Billing

RedBTC AI Gateway API

FREE