API Reference

This document provides the complete API reference for EMCP Token, helping developers quickly integrate with and use EMCP Token.

Interface Overview

Compatibility Notes

EMCP Token is fully compatible with the OpenAI interface format; you can use it by simply replacing the official domain. For example:

  • OpenAI official domain: https://api.openai.com/v1
  • EMCP Token domain: https://api.xftoken.ctclouds.com/v1

Access Domain

  • API service: api.xftoken.ctclouds.com
  • API version: v1
  • Protocol: HTTPS

Protocol Support

On top of the OpenAI Chat Completions / Completions protocols, EMCP Token adds support for Responses, Anthropic Messages, and the Gemini native protocol, enabling direct integration by clients such as Codex, Claude Code, and Gemini CLI.

Protocol TypeEndpointTypical Scenario
OpenAI Chat Completions/v1/chat/completionsGeneral conversation, multi-turn text interaction
OpenAI Completions/v1/completionsTraditional text completion, continuation
OpenAI Responses/v1/responsesCodex, OpenAI's new clients, and tool-calling scenarios
Anthropic Messages/v1/messagesClaude Code, native Claude Messages invocation
Gemini Native Interface/v1beta/models/{model}:generateContentGemini CLI, native Gemini model invocation
Images Generations/v1/images/generationsGPT Image generation

Authentication

API Key Authentication

EMCP Token uses an API key for authentication. You must include the Authorization field in the request header in the format Bearer YOUR_API_KEY.

Request Header Conventions

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

General Conventions

Request Format

All API requests use the JSON format and require Content-Type: application/json in the request header.

Response Format Conventions

All API responses use the JSON format. Text interfaces typically include the following fields:

  • id: unique identifier of the request
  • object: the object type of the response
  • created: the timestamp when the response was created
  • model: the name of the model used
  • choices: the list of results generated by the model
  • usage: usage information, including Token consumption

Image interfaces return base64-encoded image content in the JSON, e.g., candidates[].content.parts[].inlineData.data for the Gemini image interface, or data[].b64_json for the GPT Image interface.

Common Request Headers

  • Authorization: API key authentication information
  • Content-Type: request content type, typically application/json
  • User-Agent: client identifier

Common Response Fields

  • id: unique identifier of the request
  • object: the object type of the response
  • created: the timestamp when the response was created
  • model: the name of the model used
  • choices: the list of results generated by the model
  • usage: usage information, including Token consumption
  • data: result data returned by image and other interfaces
  • error: error information (only present when an error occurs)

Core Endpoint Details

Chat Completions

Purpose

Used for text conversation and multi-turn interaction.

Request Method

  • Method: POST
  • URL: https://api.xftoken.ctclouds.com/v1/chat/completions
  • Auth: API key required

Request Parameters

  • model: model name (required)
  • messages: message list (required)
    • role: role, optional values are "system", "user", "assistant"
    • content: message content
  • temperature: sampling temperature, range 0–2, default 1
  • top_p: nucleus sampling, range 0–1, default 1
  • n: number of generated replies, default 1
  • stream: whether to use streaming responses, default false
  • stop: stop sequence
  • max_tokens: maximum number of Tokens to generate
  • presence_penalty: presence penalty, range -2 to 2
  • frequency_penalty: frequency penalty, range -2 to 2

Response Fields

  • id: unique identifier of the request
  • object: value is "chat.completion"
  • created: the timestamp when the response was created
  • model: the name of the model used
  • choices: the list of generated results
    • index: result index
    • message: the generated message
      • role: role
      • content: content
    • finish_reason: completion reason
  • usage: usage information
    • prompt_tokens: number of input Tokens
    • completion_tokens: number of output Tokens
    • total_tokens: total number of Tokens

Code Examples

Basic Call
import requests

url = "https://api.xftoken.ctclouds.com/v1/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "model": "claude-sonnet-4-6",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello, EMCP Token!"}
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
Streaming Call
import requests
import json

url = "https://api.xftoken.ctclouds.com/v1/chat/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "model": "claude-sonnet-4-6",
    "messages": [
        {"role": "user", "content": "Write a short story about AI."}
    ],
    "stream": True
}

response = requests.post(url, headers=headers, json=data, stream=True)

for line in response.iter_lines():
    if line:
        decoded_line = line.decode('utf-8')
        if decoded_line.startswith('data: '):
            data = decoded_line[6:]
            if data == '[DONE]':
                break
            try:
                json_data = json.loads(data)
                if 'choices' in json_data and len(json_data['choices']) > 0:
                    delta = json_data['choices'][0].get('delta', {})
                    if 'content' in delta:
                        print(delta['content'], end='')
            except json.JSONDecodeError:
                pass

Completions

Purpose

Used for text completion, continuation, and generation.

Request Method

  • Method: POST
  • URL: https://api.xftoken.ctclouds.com/v1/completions
  • Auth: API key required

Request Parameters

  • model: model name (required)
  • prompt: prompt text (required)
  • temperature: sampling temperature, range 0–2, default 1
  • top_p: nucleus sampling, range 0–1, default 1
  • n: number of generated replies, default 1
  • stream: whether to use streaming responses, default false
  • stop: stop sequence
  • max_tokens: maximum number of Tokens to generate
  • presence_penalty: presence penalty, range -2 to 2
  • frequency_penalty: frequency penalty, range -2 to 2

Response Fields

  • id: unique identifier of the request
  • object: value is "text_completion"
  • created: the timestamp when the response was created
  • model: the name of the model used
  • choices: the list of generated results
    • index: result index
    • text: the generated text
    • finish_reason: completion reason
  • usage: usage information
    • prompt_tokens: number of input Tokens
    • completion_tokens: number of output Tokens
    • total_tokens: total number of Tokens

Code Example

import requests

url = "https://api.xftoken.ctclouds.com/v1/completions"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "model": "claude-sonnet-4-6",
    "prompt": "Write a poem about AI",
    "max_tokens": 100
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Responses

Purpose

Compatible with the OpenAI Responses protocol, suitable for Codex, OpenAI's new clients, and scenarios requiring tool-calling capabilities.

Request Method

  • Method: POST
  • URL: https://api.xftoken.ctclouds.com/v1/responses
  • Auth: API key required

Request Parameters

  • model: model name (required)
  • input: input content (required), can be a string or a message array
  • instructions: system instructions (optional)
  • max_output_tokens: maximum number of output Tokens (optional)
  • temperature: sampling temperature (optional)
  • stream: whether to use streaming responses, default false

Response Fields

  • id: unique identifier of the request
  • object: response object type
  • model: the name of the model used
  • output: list of model output content
  • output_text: aggregated text output
  • usage: Token usage

Code Example

import requests

url = "https://api.xftoken.ctclouds.com/v1/responses"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "model": "gpt-5.4",
    "input": "Introduce EMCP Token's capabilities in three sentences"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Messages

Purpose

Compatible with the Anthropic Messages protocol, suitable for Claude Code, native Claude clients, and Claude model invocation scenarios.

Request Method

  • Method: POST
  • URL: https://api.xftoken.ctclouds.com/v1/messages
  • Auth: API key required

Request Parameters

  • model: model name (required)
  • messages: message list (required)
    • role: role, optional values are "user", "assistant"
    • content: message content
  • system: system instructions (optional)
  • max_tokens: maximum number of output Tokens (required)
  • temperature: sampling temperature (optional)
  • stream: whether to use streaming responses, default false

Response Fields

  • id: unique identifier of the request
  • type: response type, typically "message"
  • role: response role
  • model: the name of the model used
  • content: list of output content
    • type: content type, text is typically "text"
    • text: model output text
  • stop_reason: stop reason
  • usage: Token usage

Code Example

import requests

url = "https://api.xftoken.ctclouds.com/v1/messages"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
    "anthropic-version": "2023-06-01"
}
data = {
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Write a Python quicksort example"}
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Gemini Native Interface

Purpose

Compatible with the Gemini generateContent protocol, suitable for Gemini CLI, the native Gemini SDK, or scenarios that need to organize contents in the Gemini format.

Request Method

  • Method: POST
  • URL: https://api.xftoken.ctclouds.com/v1beta/models/{model}:generateContent
  • Auth: API key required

Request Parameters

  • contents: list of input content (required)
    • parts: list of input segments (required)
      • text: text prompt
  • generationConfig: generation configuration (optional)
    • temperature: sampling temperature
    • topP: nucleus sampling parameter
    • topK: Top-K sampling parameter
    • maxOutputTokens: maximum number of output Tokens

Response Fields

  • candidates: list of candidate results
    • content: content returned by the model
      • parts: list of result segments
        • text: model output text
    • finishReason: generation end reason
  • usageMetadata: Token usage
  • modelVersion: the actual model version that responded

Code Example

import requests

model = "gemini-3-flash-preview"
url = f"https://api.xftoken.ctclouds.com/v1beta/models/{model}:generateContent"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "contents": [
        {
            "parts": [
                {"text": "Explain what an API aggregation platform is in one sentence"}
            ]
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Gemini Image Generation Interface

Purpose

Generate images from text prompts via Gemini image models.

Request Method

  • Method: POST
  • URL: https://api.xftoken.ctclouds.com/v1/models/{model}:generateContent
  • Auth: API key required

Supported Models

  • gemini-3-pro-image-preview
  • gemini-3.1-flash-image-preview

Request Parameters

  • contents: list of input content (required)
    • parts: list of input segments (required)
      • text: image generation prompt (required)
  • generationConfig: generation configuration (optional)
    • candidateCount: number of candidate results, recommended 1
    • temperature: sampling temperature
    • topP: nucleus sampling parameter
    • topK: Top-K sampling parameter
    • imageConfig: image configuration
      • aspectRatio: image aspect ratio, e.g., "1:1"
      • imageSize: image size tier, e.g., "1K"

Response Fields

  • candidates: list of candidate results
    • content: content returned by the model
      • parts: list of result segments
        • inlineData: image data object
          • mimeType: image MIME type, e.g., "image/png", "image/jpeg"
          • data: base64-encoded image content
    • finishReason: generation end reason, normally "STOP" on success
  • usageMetadata: Token usage
  • modelVersion: the actual model version that responded

Code Examples

Basic Call
import requests

model = "gemini-3-pro-image-preview"
url = f"https://api.xftoken.ctclouds.com/v1/models/{model}:generateContent"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "contents": [
        {
            "parts": [
                {"text": "Draw a red cup"}
            ]
        }
    ],
    "generationConfig": {
        "candidateCount": 1,
        "imageConfig": {
            "aspectRatio": "1:1",
            "imageSize": "1K"
        }
    }
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
Saving the Image
import base64

result = response.json()
inline_data = result["candidates"][0]["content"]["parts"][0]["inlineData"]
image_base64 = inline_data["data"]
mime_type = inline_data["mimeType"]

ext = "png"
if mime_type == "image/jpeg":
    ext = "jpg"
elif mime_type == "image/webp":
    ext = "webp"

with open(f"output.{ext}", "wb") as f:
    f.write(base64.b64decode(image_base64))

Usage Notes

  • A text-to-image request requires at least one text segment
  • Multiple text segments can be used to split the prompt
  • Images are returned as base64 strings; the client must decode and save them itself
  • It is recommended to determine the file format based on the mimeType in the response

GPT Image Generation Interface

Purpose

Generate images from text prompts via the GPT Image model.

Request Method

  • Method: POST
  • URL: https://api.xftoken.ctclouds.com/v1/images/generations
  • Auth: API key required

Supported Models

  • gpt-image-2

Request Parameters

  • model: model name (required), currently supports "gpt-image-2"
  • prompt: image generation prompt (required)
  • n: number of images to generate, recommended 1
  • size: image size, e.g., "1024x1024"
  • quality: image quality, e.g., "low"
  • output_format: output image format, e.g., "png", "jpeg", "webp"
  • background: background type, e.g., "opaque", "auto"
  • output_compression: output compression parameter, typically used for JPEG/WebP and similar formats

Response Fields

  • created: response creation timestamp
  • background: the actual background type returned
  • data: list of generated image results
    • b64_json: base64-encoded image content
  • output_format: the actual image format returned
  • quality: the actual or returned image quality
  • size: the actual image size returned
  • usage: Token usage
    • input_tokens: number of input Tokens
    • output_tokens: number of output Tokens
    • total_tokens: total number of Tokens

Code Examples

Basic Call
import requests

url = "https://api.xftoken.ctclouds.com/v1/images/generations"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}
data = {
    "model": "gpt-image-2",
    "prompt": "Draw a blue square icon",
    "n": 1,
    "size": "1024x1024",
    "quality": "low",
    "output_format": "png",
    "background": "opaque"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
Saving the Image
import base64

result = response.json()
image_base64 = result["data"][0]["b64_json"]
output_format = result.get("output_format", "png")

with open(f"output.{output_format}", "wb") as f:
    f.write(base64.b64decode(image_base64))

Usage Notes

  • prompt must not be empty
  • It is recommended to use n=1 by default to control generation cost
  • If fixed dimensions are required by the business, explicitly pass size
  • Images are returned as base64 strings; the client must decode and save them itself
  • It is recommended to save the file extension based on the output_format in the response

Models List Interface

Purpose

List all available models.

Request Method

  • Method: GET
  • URL: https://api.xftoken.ctclouds.com/v1/models
  • Auth: API key required

Request Parameters

None

Response Fields

  • object: value is "list"
  • data: model list
    • id: model ID
    • object: value is "model"
    • created: model creation timestamp
    • owned_by: model owner

Code Example

import requests

url = "https://api.xftoken.ctclouds.com/v1/models"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

Exception Handling

  • 401 Unauthorized: API key is invalid or expired
  • 403 Forbidden: API key does not have sufficient permissions
  • 500 Internal Server Error: internal server error

Model Detail Interface

Purpose

Get detailed information about a specific model.

Request Method

  • Method: GET
  • URL: https://api.xftoken.ctclouds.com/v1/models/{model_id}
  • Auth: API key required

Request Parameters

  • model_id: model ID (path parameter, required)

Response Fields

  • id: model ID
  • object: value is "model"
  • created: model creation timestamp
  • owned_by: model owner

Code Example

import requests

model_id = "claude-sonnet-4-6"
url = f"https://api.xftoken.ctclouds.com/v1/models/{model_id}"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

Exception Handling

  • 401 Unauthorized: API key is invalid or expired
  • 403 Forbidden: API key does not have sufficient permissions
  • 404 Not Found: model does not exist
  • 500 Internal Server Error: internal server error

Account Balance Query Interface

Purpose

Query the available balance of the current account.

Request Method

  • Method: GET
  • URL: https://api.xftoken.ctclouds.com/v1/account/balance
  • Auth: API key required

Request Parameters

None

Response Fields

  • balance: available account balance
  • currency: currency type, default USD
  • updated_at: balance update time

Code Example

import requests

url = "https://api.xftoken.ctclouds.com/v1/account/balance"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

Exception Handling

  • 401 Unauthorized: API key is invalid or expired
  • 403 Forbidden: API key does not have sufficient permissions
  • 500 Internal Server Error: internal server error