OpenAI SDK Compatibility#

Tokenthon provides a compatibility layer that enables you to use the standard OpenAI SDK to access our powerful AI models. With minimal code changes, you can quickly integrate Tokenthon's cost-effective AI capabilities into your existing applications.

Getting Started with the OpenAI SDK#

To use the OpenAI SDK compatibility feature, you'll need to:

1. Use an official OpenAI SDK (or any compatible HTTP client)
2. Update your base URL to point to Tokenthon's API
3. Replace your API key with a Tokenthon API key
4. Use Tokenthon model names (e.g., gpt-auto, gpt-5-mini, gpt-5, gpt-5.2)
5. Review the documentation below for what features are supported

Quick Start Example#

from openai import OpenAI
 
client = OpenAI(
    api_key="YOUR_TOKENTHON_API_KEY",
    base_url="https://api.tokenthon.com/v1/"
)
 
response = client.chat.completions.create(
    model="gpt-auto", # Tokenthon auto-selects the best model
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Who are you?"}
    ],
)
 
print(response.choices[0].message.content)

Supported Models#

Tokenthon supports the following model names through the OpenAI compatibility layer:

Important Compatibility Limitations#

API Behavior#

Here are the most substantial differences from using the standard OpenAI API:

• Streaming is not supported - The stream parameter is accepted but not implemented. All responses are returned as complete messages.
• Tool calling is not supported - Tool messages (role: "tool") and function calling are filtered out and not processed.
• Most parameters are ignored - Parameters like temperature, top_p, stop, presence_penalty, frequency_penalty, and others are accepted by the schema but not used in the actual processing.
• Response format validation - JSON schema validation is performed by the model but not strictly enforced by Tokenthon.
• Multiple choices not supported - The n parameter must be exactly 1.

Most unsupported fields are silently ignored rather than producing errors. These are all documented below.

Output Quality Considerations#

If you've done lots of tweaking to your prompt, it's likely to be well-tuned to OpenAI specifically. You may need to adjust your prompts slightly when migrating to Tokenthon, especially if you rely on features that are not supported in our compatibility layer.

System Message Handling#

Tokenthon's compatibility layer supports both system and developer roles. However, our internal API uses a slightly different role system:

• OpenAI system messages are mapped to Tokenthon's developer role
• OpenAI developer messages are mapped to Tokenthon's developer role
• user and assistant roles remain unchanged

This mapping is handled automatically, so you don't need to change your message structure.

Rate Limits#

Rate limits follow Tokenthon's standard limits for the /v1/chat/completions endpoint. Please refer to your account dashboard or contact support for specific rate limit details.

Detailed OpenAI Compatible API Support#

Request Fields#

Simple Fields#

tools / functions Fields#

Tools (tools[n].function fields)

Functions (functions[n] fields)

OpenAI has deprecated the functions field and suggests using tools instead.

messages Array Fields#

Developer Role

Fields for messages[n].role == "developer"

System Role

Fields for messages[n].role == "system"

User Role

Fields for messages[n].role == "user"

Assistant Role

Fields for messages[n].role == "assistant"

Tool Role

Fields for messages[n].role == "tool"

Function Role

Fields for messages[n].role == "function"

Response Fields#

Error Message Compatibility#

The compatibility layer maintains consistent error formats with the OpenAI API. Error responses include:

{
    "error": {
        "message": "Error description here",
        "type": "error_type",
        "param": undefined,
        "code": "status_code_string"
    }
}

Error types are mapped based on HTTP status codes:

The detailed error messages will not be equivalent to OpenAI's. We recommend only using the error messages for logging and debugging.

Header Compatibility#

While the OpenAI SDK automatically manages headers, here is the complete list of headers supported by the Tokenthon API for developers who need to work with them directly.

Note: Tokenthon does not return rate limit headers in the current implementation. Please monitor your usage through the dashboard.

Examples#

JSON Mode#

response = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant that responds in JSON."},
        {"role": "user", "content": "Extract the name and age from this text: John is 25 years old."}
    ],
    response_format={"type": "json_object"}
)
 
print(response.choices[0].message.content)

JSON Schema Mode#

response = client.chat.completions.create(
    model="gpt-5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Extract structured data from this text: The meeting is on January 15, 2024 at 3 PM."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "event_extraction",
            "schema": {
                "type": "object",
                "properties": {
                    "date": {"type": "string"},
                    "time": {"type": "string"}
                },
                "required": ["date", "time"]
            }
        }
    }
)
 
print(response.choices[0].message.content)

Multiple Messages with All Roles#

response = client.chat.completions.create(
    model="gpt-auto",
    messages=[
        {"role": "system", "content": "You are a helpful customer service agent."},
        {"role": "user", "content": "I have a question about my order."},
        {"role": "assistant", "content": "I'd be happy to help! What's your order number?"},
        {"role": "user", "content": "Order #12345"}
    ]
)
 
print(response.choices[0].message.content)