API Reference v1.0

Base URL: https://www.tokencnn.com · Full OpenAI SDK compatibility · JSON in / JSON out

🔐 Authentication

All API requests require a Bearer token in the Authorization header. Generate your API key from the Console → Token Management.

# Include this header on every request
Authorization: Bearer ***

All requests must also include Content-Type: application/json (except multipart uploads for audio and image endpoints).

OpenAI SDK Quick Setup

from openai import OpenAI

client = OpenAI(
    base_url="https://www.tokencnn.com",
    api_key="sk-your-api-key-here"
)

# Now use client just like you would with OpenAI
response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Hello!"}]
)

⚠️ Error Codes

tokencnn.com uses standard HTTP status codes and returns JSON error bodies with descriptive messages.

Status Code	Meaning	Typical Cause
200 OK	Request succeeded	—
400 Bad Request	Invalid request body or parameters	Missing required fields, malformed JSON
401 Unauthorized	Authentication failed	Missing, invalid, or expired API key
402 Payment Required	Insufficient balance	Account needs a top-up
404 Not Found	Endpoint or model not found	Invalid model ID or URL
429 Too Many Requests	Rate limit exceeded	Too many requests in a short period
500 Internal Server Error	Server-side failure	Retry with exponential backoff

Error response body format:

{
    "error": {
        "message": "Insufficient balance. Please top up your account.",
        "type": "insufficient_funds",
        "code": 402
    }
}

📦 Models

List Available Models

Retrieve a list of all models available on your account. Compatible with OpenAI.models.list().

cURL

curl https://www.tokencnn.com/v1/models \
  -H "Authorization: Bearer sk-your-api-key-here"

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://www.tokencnn.com",
    api_key="sk-your-api-key-here"
)

models = client.models.list()
for model in models:
    print(model.id)

Response

{
    "object": "list",
    "data": [
        {
            "id": "deepseek-chat",
            "object": "model",
            "created": 1700000000,
            "owned_by": "tokencnn"
        },
        {
            "id": "qwen-max",
            "object": "model",
            "created": 1700000001,
            "owned_by": "tokencnn"
        }
    ]
}

💬 Chat Completions

Chat Completions (OpenAI Format)

Full compatibility with the OpenAI Chat Completions API. Supports multi-turn conversations, system prompts, streaming, function/tool calling, and all standard parameters.

Request Body Parameters

Parameter	Type	Required	Description
model	string	Yes	Model ID (e.g. "deepseek-chat", "qwen-max")
messages	array	Yes	List of message objects with role (system, user, assistant, tool) and content
temperature	number	No	Sampling temperature (0–2). Default: 1.0
max_tokens	integer	No	Maximum tokens in the response
stream	boolean	No	Enable streaming (SSE). Default: false
top_p	number	No	Nucleus sampling parameter (0–1)
frequency_penalty	number	No	Frequency penalty (–2 to 2)
presence_penalty	number	No	Presence penalty (–2 to 2)
stop	string | array	No	Up to 4 stop sequences
tools	array	No	Tool/function calling definitions

cURL

curl https://www.tokencnn.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {"role": "system", "content": "You are a helpful AI assistant."},
      {"role": "user", "content": "What are the top Chinese AI models available today?"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://www.tokencnn.com",
    api_key="sk-your-api-key-here"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "You are a helpful AI assistant."},
        {"role": "user", "content": "What are the top Chinese AI models available today?"}
    ],
    temperature=0.7,
    max_tokens=1024
)

print(response.choices[0].message.content)

Response

{
    "id": "chatcmpl-abc123def456",
    "object": "chat.completion",
    "created": 1700000000,
    "model": "deepseek-chat",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "China has several leading AI models including DeepSeek, Qwen (Alibaba), GLM (Zhipu AI), Kimi (Moonshot AI), and Doubao (ByteDance). Each excels in different areas..."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 25,
        "completion_tokens": 85,
        "total_tokens": 110
    }
}

Claude Native Format

Use the Anthropic Claude Messages API format with tokencnn.com models. Perfect for migrating from the Anthropic SDK — just change the base_url.

Request Body Parameters

Parameter	Type	Required	Description
model	string	Yes	Model ID
messages	array	Yes	List of messages with role (user, assistant)
system	string	No	System prompt (Claude-style)
max_tokens	integer	Yes	Maximum output tokens
temperature	number	No	Sampling temperature (0–1)

cURL

curl https://www.tokencnn.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "deepseek-chat",
    "system": "You are a knowledgeable AI assistant.",
    "messages": [
      {"role": "user", "content": "Explain how Chinese AI models compare to GPT-4."}
    ],
    "max_tokens": 1024,
    "temperature": 0.7
  }'

Python

import anthropic

client = anthropic.Anthropic(
    base_url="https://www.tokencnn.com",
    api_key="sk-your-api-key-here"
)

response = client.messages.create(
    model="deepseek-chat",
    system="You are a knowledgeable AI assistant.",
    messages=[
        {"role": "user", "content": "Explain how Chinese AI models compare to GPT-4."}
    ],
    max_tokens=1024
)

print(response.content[0].text)

Response

{
    "id": "msg_abc123def456",
    "type": "message",
    "role": "assistant",
    "content": [
        {
            "type": "text",
            "text": "Chinese AI models like DeepSeek, Qwen, and GLM have achieved remarkable performance..."
        }
    ],
    "model": "deepseek-chat",
    "stop_reason": "end_turn",
    "usage": {
        "input_tokens": 18,
        "output_tokens": 92
    }
}

Gemini Native Format

Use Google's Gemini native format to generate content. Fully compatible with the Google Generative AI SDK.

Path Parameters

Parameter	Description
model	Model name, e.g. deepseek-chat

cURL

curl https://www.tokencnn.com/v1beta/models/deepseek-chat:generateContent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {"text": "What makes DeepSeek unique among Chinese AI models?"}
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.8,
      "maxOutputTokens": 1024
    }
  }'

Python (Gemini SDK)

import google.generativeai as genai

genai.configure(
    api_key="sk-your-api-key-here",
    transport="rest",
    client_options={"api_endpoint": "https://www.tokencnn.com"}
)

model = genai.GenerativeModel("deepseek-chat")
response = model.generate_content(
    "What makes DeepSeek unique among Chinese AI models?"
)
print(response.text)

Response

{
    "candidates": [
        {
            "content": {
                "role": "model",
                "parts": [
                    {"text": "DeepSeek stands out for its exceptional reasoning capabilities and cost-efficiency..."}
                ]
            },
            "finishReason": "STOP"
        }
    ],
    "usageMetadata": {
        "promptTokenCount": 12,
        "candidatesTokenCount": 78,
        "totalTokenCount": 90
    }
}

🧠 Embeddings & Rerank

Text Embeddings

Convert text into high-dimensional vector representations. Compatible with the OpenAI Embeddings API.

Request Body Parameters

Parameter	Type	Required	Description
model	string	Yes	Embedding model ID (e.g. "text-embedding-v3")
input	string | array	Yes	Text or array of texts to embed
encoding_format	string	No	Output format: "float" or "base64"

cURL

curl https://www.tokencnn.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "text-embedding-v3",
    "input": "China's AI ecosystem is growing rapidly with models like DeepSeek and Qwen."
  }'

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://www.tokencnn.com",
    api_key="sk-your-api-key-here"
)

response = client.embeddings.create(
    model="text-embedding-v3",
    input="China's AI ecosystem is growing rapidly with models like DeepSeek and Qwen."
)

print(response.data[0].embedding[:5])  # First 5 values

Response

{
    "object": "list",
    "data": [
        {
            "object": "embedding",
            "index": 0,
            "embedding": [-0.009327, 0.025204, -0.018571, 0.003689, ...]
        }
    ],
    "model": "text-embedding-v3",
    "usage": {
        "prompt_tokens": 12,
        "total_tokens": 12
    }
}

Document Reranking

Given a query and a set of candidate documents, returns them sorted by relevance score. Ideal for improving RAG (Retrieval-Augmented Generation) pipelines.

Request Body Parameters

Parameter	Type	Required	Description
model	string	Yes	Reranker model ID
query	string	Yes	Search query text
documents	array[string]	Yes	Candidate documents to re-rank
top_n	integer	No	Number of top results to return (default: all)
return_documents	boolean	No	Include original document text in results

cURL

curl https://www.tokencnn.com/v1/rerank \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "rerank-v1",
    "query": "Latest breakthroughs in Chinese AI models",
    "documents": [
      "DeepSeek released a new reasoning model with chain-of-thought capabilities",
      "The weather today is sunny with a high of 25 degrees",
      "Alibaba's Qwen 2.5 achieves state-of-the-art results on coding benchmarks",
      "Zhipu AI announced GLM-4 with enhanced multimodal understanding"
    ],
    "top_n": 3,
    "return_documents": true
  }'

Python

import requests

response = requests.post(
    "https://www.tokencnn.com/v1/rerank",
    headers={
        "Authorization": "Bearer sk-your-api-key-here",
        "Content-Type": "application/json"
    },
    json={
        "model": "rerank-v1",
        "query": "Latest breakthroughs in Chinese AI models",
        "documents": [
            "DeepSeek released a new reasoning model with chain-of-thought capabilities",
            "The weather today is sunny",
            "Alibaba's Qwen 2.5 achieves state-of-the-art results",
            "Zhipu AI announced GLM-4 with enhanced multimodal understanding"
        ],
        "top_n": 3,
        "return_documents": True
    }
)

for result in response.json()["results"]:
    print(f"Score: {result['relevance_score']:.3f} - {result['document']['text']}")

Response

{
    "results": [
        {
            "index": 0,
            "document": {"text": "DeepSeek released a new reasoning model with chain-of-thought capabilities"},
            "relevance_score": 0.958
        },
        {
            "index": 2,
            "document": {"text": "Alibaba's Qwen 2.5 achieves state-of-the-art results on coding benchmarks"},
            "relevance_score": 0.901
        },
        {
            "index": 3,
            "document": {"text": "Zhipu AI announced GLM-4 with enhanced multimodal understanding"},
            "relevance_score": 0.872
        }
    ],
    "meta": {"tokens_used": 42}
}

🎨 Image Generation

Generate Images

Generate images from text prompts. Compatible with the OpenAI Images API format. Supports multiple sizes and styles.

Request Body Parameters

Parameter	Type	Required	Description
model	string	No	Image model ID (defaults to latest)
prompt	string	Yes	Text description of the image
n	integer	No	Number of images to generate (default: 1)
size	string	No	Image size, e.g. "1024x1024", "1792x1024"
quality	string	No	"standard" or "hd"
style	string	No	"vivid" or "natural"

cURL

curl https://www.tokencnn.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "flux-pro",
    "prompt": "A giant panda coding on a laptop in a bamboo forest, digital art style",
    "n": 1,
    "size": "1024x1024",
    "quality": "hd"
  }'

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://www.tokencnn.com",
    api_key="sk-your-api-key-here"
)

response = client.images.generate(
    model="flux-pro",
    prompt="A giant panda coding on a laptop in a bamboo forest, digital art style",
    n=1,
    size="1024x1024"
)

print(response.data[0].url)

Response

{
    "created": 1700000000,
    "data": [
        {
            "url": "https://www.tokencnn.com/storage/images/abc123.png",
            "revised_prompt": "A giant panda sitting at a laptop, coding, surrounded by bamboo forest, digital art style, vibrant colors"
        }
    ]
}

🎵 Audio API

Text-to-Speech (TTS)

Generate lifelike speech audio from text. Compatible with the OpenAI TTS API format.

Request Body Parameters

Parameter	Type	Required	Description
model	string	No	TTS model ID
input	string	Yes	Text to convert to speech (max 4096 characters)
voice	string	No	Voice: "alloy", "echo", "fable", "onyx", "nova", "shimmer"
response_format	string	No	Audio format: "mp3", "opus", "aac", "flac", "wav"
speed	number	No	Speech speed (0.25–4.0). Default: 1.0

cURL

curl https://www.tokencnn.com/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -d '{
    "model": "tts-1",
    "input": "Welcome to tokencnn.com — China's AI gateway for global developers.",
    "voice": "nova",
    "response_format": "mp3",
    "speed": 1.0
  }' \
  --output speech.mp3

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://www.tokencnn.com",
    api_key="sk-your-api-key-here"
)

response = client.audio.speech.create(
    model="tts-1",
    voice="nova",
    input="Welcome to tokencnn.com — China's AI gateway for global developers.",
    response_format="mp3"
)

response.stream_to_file("speech.mp3")

Response

The response is binary audio data (MP3 by default). The Content-Type header indicates the format. Save to file for playback.

Speech-to-Text (Transcription)

Transcribe audio files to text. Compatible with the OpenAI Audio Transcriptions API.

Request Parameters (multipart/form-data)

Parameter	Type	Required	Description
file	file	Yes	Audio file (mp3, wav, ogg, flac, m4a, etc.)
model	string	No	Transcription model ID
language	string	No	ISO-639-1 language code (e.g. "en", "zh")
response_format	string	No	Output: "json", "text", "srt", "verbose_json", "vtt"
temperature	number	No	Sampling temperature (0–1)

cURL

curl https://www.tokencnn.com/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -F "file=@/path/to/audio.mp3" \
  -F "model=whisper-1" \
  -F "language=en" \
  -F "response_format=json"

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://www.tokencnn.com",
    api_key="sk-your-api-key-here"
)

with open("audio.mp3", "rb") as f:
    response = client.audio.transcriptions.create(
        model="whisper-1",
        file=f,
        language="en",
        response_format="json"
    )

print(response.text)

Response

{
    "text": "Welcome to tokencnn.com, China's AI gateway for global developers. We provide access to over 30 top Chinese and international AI models through a single unified API."
}

Speech Translation

Translate audio from any language into English text. Compatible with the OpenAI Audio Translations API. Input can be in any language; output is always English.

Request Parameters (multipart/form-data)

Parameter	Type	Required	Description
file	file	Yes	Audio file to translate
model	string	No	Translation model ID
response_format	string	No	Output format
temperature	number	No	Sampling temperature (0–1)

cURL

curl https://www.tokencnn.com/v1/audio/translations \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -F "file=@/path/to/chinese_speech.mp3" \
  -F "model=whisper-1" \
  -F "response_format=json"

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://www.tokencnn.com",
    api_key="sk-your-api-key-here"
)

with open("chinese_speech.mp3", "rb") as f:
    response = client.audio.translations.create(
        model="whisper-1",
        file=f,
        response_format="json"
    )

print(response.text)

Response

{
    "text": "Welcome to tokencnn.com, China's unified AI gateway for global developers. We provide text generation, multimodal understanding, embeddings, image generation, and audio capabilities through a single API."
}

⚙️ Management APIs

The following management endpoints allow programmatic access to administrative features. All require a Management API key with the appropriate permissions. These endpoints are for administrators and automated workflows.

System Settings

Retrieve current system-wide settings and configuration values.

cURL

curl https://www.tokencnn.com/v1/admin/settings \
  -H "Authorization: Bearer mgmt-your-api-key"

Python

import requests

response = requests.get(
    "https://www.tokencnn.com/v1/admin/settings",
    headers={"Authorization": "Bearer mgmt-your-api-key"}
)
print(response.json())

Response

{
    "system_name": "tokencnn.com",
    "version": "1.0.0",
    "features": {
        "registration_enabled": true,
        "maintenance_mode": false,
        "default_currency": "USD"
    },
    "rate_limits": {
        "requests_per_minute": 60,
        "tokens_per_minute": 100000
    }
}

Channel Management

Manage upstream AI model channels. Channels represent the underlying providers that power tokencnn.com's model catalog.

cURL

curl https://www.tokencnn.com/v1/admin/channels \
  -H "Authorization: Bearer mgmt-your-api-key"

Response

{
    "channels": [
        {
            "id": "ch_deepseek",
            "name": "DeepSeek Official",
            "status": "active",
            "models": ["deepseek-chat", "deepseek-reasoner"],
            "priority": 1
        },
        {
            "id": "ch_qwen",
            "name": "Alibaba Qwen",
            "status": "active",
            "models": ["qwen-max", "qwen-plus"],
            "priority": 2
        }
    ]
}

User Management

List all registered users with their account status, balance, and usage metrics. Requires admin privileges.

cURL

curl https://www.tokencnn.com/v1/admin/users?page=1&limit=20 \
  -H "Authorization: Bearer mgmt-your-api-key"

Response

{
    "users": [
        {
            "id": "usr_abc123",
            "email": "dev@example.com",
            "status": "active",
            "balance": 25.50,
            "total_usage": 142.30,
            "created_at": "2026-01-15T08:30:00Z"
        }
    ],
    "total": 42,
    "page": 1,
    "limit": 20
}

Token Management

Retrieve and manage all API tokens across users. Create, revoke, or update token permissions.

cURL

curl https://www.tokencnn.com/v1/admin/tokens \
  -H "Authorization: Bearer mgmt-your-api-key"

Response

{
    "tokens": [
        {
            "id": "tok_xyz789",
            "name": "Production App",
            "user_id": "usr_abc123",
            "permissions": ["chat", "embeddings"],
            "status": "active",
            "created_at": "2026-03-01T12:00:00Z",
            "last_used": "2026-05-30T14:22:00Z"
        }
    ]
}

Payment & Top-Up

Add credits to a user's account programmatically. Supports multiple payment methods and currency amounts.

Request Body Parameters

Parameter	Type	Required	Description
user_id	string	Yes	Target user ID
amount	number	Yes	Amount in USD
payment_method	string	No	Payment method ID or "balance"

cURL

curl https://www.tokencnn.com/v1/admin/topup \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer mgmt-your-api-key" \
  -d '{
    "user_id": "usr_abc123",
    "amount": 50.00
  }'

Response

{
    "success": true,
    "transaction_id": "txn_def456",
    "user_id": "usr_abc123",
    "amount": 50.00,
    "new_balance": 75.50,
    "timestamp": "2026-05-31T10:00:00Z"
}

Usage Logs

Retrieve detailed usage logs for auditing, billing, and analytics. Supports date range filtering and pagination.

Query Parameters

Parameter	Type	Required	Description
user_id	string	No	Filter by user
start_date	string	No	Start date (ISO 8601)
end_date	string	No	End date (ISO 8601)
page	integer	No	Page number (default: 1)
limit	integer	No	Results per page (default: 50, max: 200)

cURL

curl "https://www.tokencnn.com/v1/admin/usage?start_date=2026-05-01&end_date=2026-05-31&page=1&limit=20" \
  -H "Authorization: Bearer mgmt-your-api-key"

Response

{
    "usage": [
        {
            "id": "log_001",
            "user_id": "usr_abc123",
            "model": "deepseek-chat",
            "endpoint": "/v1/chat/completions",
            "prompt_tokens": 150,
            "completion_tokens": 320,
            "cost": 0.0047,
            "timestamp": "2026-05-31T09:15:00Z"
        }
    ],
    "total": 1248,
    "page": 1,
    "limit": 20
}

---