API 参考

本文档提供了 EMCP Token 的完整 API 接口参考，帮助开发者快速集成和使用 EMCP Token。

接口概述

兼容说明

EMCP Token 完全兼容 OpenAI 接口格式，您可以直接替换官方域名使用。例如：

OpenAI 官方域名：https://api.openai.com/v1
EMCP Token 域名：https://api.xftoken.ctclouds.com/v1

接入域名

API 接口服务：api.xftoken.ctclouds.com
接口版本：v1
请求协议：HTTPS

协议支持

EMCP Token 在 OpenAI Chat Completions / Completions 协议基础上，增加了 Responses、Anthropic Messages 和 Gemini 原生协议支持，便于 Codex、Claude Code、Gemini CLI 等客户端直接接入。

协议类型	接口路径	典型场景
OpenAI Chat Completions	`/v1/chat/completions`	通用对话、多轮文本交互
OpenAI Completions	`/v1/completions`	传统文本补全、续写
OpenAI Responses	`/v1/responses`	Codex、OpenAI 新版客户端和工具调用场景
Anthropic Messages	`/v1/messages`	Claude Code、Claude 模型原生 Messages 调用
Gemini 原生接口	`/v1beta/models/{model}:generateContent`	Gemini CLI、Gemini 模型原生调用
Images Generations	`/v1/images/generations`	GPT Image 图像生成

认证与鉴权

API Key 认证方式

EMCP Token 使用 API Key 进行认证，您需要在请求头中包含 Authorization 字段，格式为 Bearer YOUR_API_KEY。

请求头配置规范

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

通用规范

请求格式

所有 API 请求都使用 JSON 格式，需要在请求头中设置 Content-Type: application/json。

响应格式规范

所有 API 响应都使用 JSON 格式。文本类接口通常包含以下字段：

id：请求的唯一标识符
object：响应的对象类型
created：响应创建的时间戳
model：使用的模型名称
choices：模型生成的结果列表
usage：使用情况，包括 Tokens 消耗

图像类接口会在 JSON 中返回 base64 编码后的图片内容，例如 Gemini 图像接口的 candidates[].content.parts[].inlineData.data，或 GPT Image 接口的 data[].b64_json。

通用请求头

Authorization：API Key 认证信息
Content-Type：请求内容类型，通常为 application/json
User-Agent：客户端标识

通用响应字段说明

id：请求的唯一标识符
object：响应的对象类型
created：响应创建的时间戳
model：使用的模型名称
choices：模型生成的结果列表
usage：使用情况，包括 Tokens 消耗
data：图像等接口返回的结果数据
error：错误信息（仅在发生错误时出现）

核心接口详情

聊天接口（Chat Completions）

接口用途

用于文本对话、多轮交互。

请求方式

方法：POST
URL：https://api.xftoken.ctclouds.com/v1/chat/completions
认证：需要 API Key

请求参数

model：模型名称（必需）
messages：消息列表（必需）
- role：角色，可选值为 "system"、"user"、"assistant"
- content：消息内容
temperature：采样温度，范围 0-2，默认 1
top_p：核采样，范围 0-1，默认 1
n：生成的回复数量，默认 1
stream：是否使用流式响应，默认 false
stop：停止词
max_tokens：最大生成 Tokens 数量
presence_penalty：存在惩罚，范围 -2-2
frequency_penalty：频率惩罚，范围 -2-2

响应字段说明

id：请求的唯一标识符
object：值为 "chat.completion"
created：响应创建的时间戳
model：使用的模型名称
choices：生成的结果列表
- index：结果索引
- message：生成的消息
  - role：角色
  - content：内容
- finish_reason：完成原因
usage：使用情况
- prompt_tokens：输入 Tokens 数量
- completion_tokens：输出 Tokens 数量
- total_tokens：总 Tokens 数量

代码示例

基础调用

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())

流式调用

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）

接口用途

用于文本补全、续写、生成。

请求方式

方法：POST
URL：https://api.xftoken.ctclouds.com/v1/completions
认证：需要 API Key

请求参数

model：模型名称（必需）
prompt：提示文本（必需）
temperature：采样温度，范围 0-2，默认 1
top_p：核采样，范围 0-1，默认 1
n：生成的回复数量，默认 1
stream：是否使用流式响应，默认 false
stop：停止词
max_tokens：最大生成 Tokens 数量
presence_penalty：存在惩罚，范围 -2-2
frequency_penalty：频率惩罚，范围 -2-2

响应字段说明

id：请求的唯一标识符
object：值为 "text_completion"
created：响应创建的时间戳
model：使用的模型名称
choices：生成的结果列表
- index：结果索引
- text：生成的文本
- finish_reason：完成原因
usage：使用情况
- prompt_tokens：输入 Tokens 数量
- completion_tokens：输出 Tokens 数量
- total_tokens：总 Tokens 数量

代码示例

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 接口

接口用途

用于兼容 OpenAI Responses 协议，适合 Codex、OpenAI 新版客户端以及需要工具调用能力的场景。

请求方式

方法：POST
URL：https://api.xftoken.ctclouds.com/v1/responses
认证：需要 API Key

请求参数

model：模型名称（必需）
input：输入内容（必需），可为字符串或消息数组
instructions：系统指令（可选）
max_output_tokens：最大输出 Tokens 数量（可选）
temperature：采样温度（可选）
stream：是否使用流式响应，默认 false

响应字段说明

id：请求的唯一标识符
object：响应对象类型
model：使用的模型名称
output：模型输出内容列表
output_text：聚合后的文本输出
usage：Token 使用情况

代码示例

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": "用三句话介绍 EMCP Token 的能力"
}

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

Messages 接口

接口用途

用于兼容 Anthropic Messages 协议，适合 Claude Code、Claude 原生客户端和 Claude 模型调用场景。

请求方式

方法：POST
URL：https://api.xftoken.ctclouds.com/v1/messages
认证：需要 API Key

请求参数

model：模型名称（必需）
messages：消息列表（必需）
- role：角色，可选值为 "user"、"assistant"
- content：消息内容
system：系统指令（可选）
max_tokens：最大输出 Tokens 数量（必需）
temperature：采样温度（可选）
stream：是否使用流式响应，默认 false

响应字段说明

id：请求的唯一标识符
type：响应类型，通常为 "message"
role：响应角色
model：使用的模型名称
content：输出内容列表
- type：内容类型，文本通常为 "text"
- text：模型输出文本
stop_reason：停止原因
usage：Token 使用情况

代码示例

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": "写一个 Python 快速排序示例"}
    ]
}

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

Gemini 原生接口

接口用途

用于兼容 Gemini generateContent 协议，适合 Gemini CLI、Gemini 原生 SDK 或需要按 Gemini 格式组织 contents 的场景。

请求方式

方法：POST
URL：https://api.xftoken.ctclouds.com/v1beta/models/{model}:generateContent
认证：需要 API Key

请求参数

contents：输入内容列表（必需）
- parts：输入片段列表（必需）
  - text：文本提示词
generationConfig：生成配置（可选）
- temperature：采样温度
- topP：核采样参数
- topK：Top-K 采样参数
- maxOutputTokens：最大输出 Tokens 数量

响应字段说明

candidates：候选结果列表
- content：模型返回内容
  - parts：结果片段列表
    - text：模型输出文本
- finishReason：生成结束原因
usageMetadata：Token 使用情况
modelVersion：实际响应的模型版本

代码示例

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": "用一句话解释什么是 API 聚合平台"}
            ]
        }
    ]
}

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

Gemini 图像生成接口

接口用途

用于通过 Gemini 图像模型根据文本提示词生成图片。

请求方式

方法：POST
URL：https://api.xftoken.ctclouds.com/v1/models/{model}:generateContent
认证：需要 API Key

支持模型

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

请求参数

contents：输入内容列表（必需）
- parts：输入片段列表（必需）
  - text：图片生成提示词（必需）
generationConfig：生成配置（可选）
- candidateCount：候选结果数量，建议为 1
- temperature：采样温度
- topP：核采样参数
- topK：Top-K 采样参数
- imageConfig：图片配置
  - aspectRatio：图片宽高比例，如 "1:1"
  - imageSize：图片尺寸档位，如 "1K"

响应字段说明

candidates：候选结果列表
- content：模型返回内容
  - parts：结果片段列表
    - inlineData：图片数据对象
      - mimeType：图片 MIME 类型，如 "image/png"、"image/jpeg"
      - data：base64 编码后的图片内容
- finishReason：生成结束原因，正常完成通常为 "STOP"
usageMetadata：Token 使用情况
modelVersion：实际响应的模型版本

代码示例

基础调用

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": "画一只红杯子"}
            ]
        }
    ],
    "generationConfig": {
        "candidateCount": 1,
        "imageConfig": {
            "aspectRatio": "1:1",
            "imageSize": "1K"
        }
    }
}

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

保存图片

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))

使用说明

文生图请求至少需要提供一个 text 片段
多个 text 片段可用于拆分提示词
图片以 base64 字符串返回，客户端需要自行解码保存
建议根据响应中的 mimeType 判断文件格式

GPT Image 图像生成接口

接口用途

用于通过 GPT Image 模型根据文本提示词生成图片。

请求方式

方法：POST
URL：https://api.xftoken.ctclouds.com/v1/images/generations
认证：需要 API Key

支持模型

gpt-image-2

请求参数

model：模型名称（必需），当前支持 "gpt-image-2"
prompt：图片生成提示词（必需）
n：生成图片数量，建议为 1
size：生成图片尺寸，如 "1024x1024"
quality：图片质量，如 "low"
output_format：输出图片格式，如 "png"、"jpeg"、"webp"
background：背景类型，如 "opaque"、"auto"
output_compression：输出压缩参数，通常用于 JPEG/WebP 等格式

响应字段说明

created：响应创建时间戳
background：实际返回的背景类型
data：生成图片结果列表
- b64_json：base64 编码后的图片内容
output_format：实际返回的图片格式
quality：实际使用或返回的图片质量
size：实际返回的图片尺寸
usage：Token 使用情况
- input_tokens：输入 Tokens 数量
- output_tokens：输出 Tokens 数量
- total_tokens：总 Tokens 数量

代码示例

基础调用

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": "画一枚蓝色方形图标",
    "n": 1,
    "size": "1024x1024",
    "quality": "low",
    "output_format": "png",
    "background": "opaque"
}

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

保存图片

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))

使用说明

prompt 不能为空
建议默认使用 n=1 控制生成成本
如果业务要求固定尺寸，建议显式传入 size
图片以 base64 字符串返回，客户端需要自行解码保存
建议根据响应中的 output_format 保存文件扩展名

模型列表接口（Models）

接口用途

列出所有可用的模型。

请求方式

方法：GET
URL：https://api.xftoken.ctclouds.com/v1/models
认证：需要 API Key

请求参数

无

响应字段说明

object：值为 "list"
data：模型列表
- id：模型 ID
- object：值为 "model"
- created：模型创建时间戳
- owned_by：模型所有者

代码示例

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())

异常处理说明

401 Unauthorized：API Key 无效或已过期
403 Forbidden：API Key 没有足够的权限
500 Internal Server Error：服务器内部错误

模型详情接口（Model）

接口用途

获取特定模型的详细信息。

请求方式

方法：GET
URL：https://api.xftoken.ctclouds.com/v1/models/{model_id}
认证：需要 API Key

请求参数

model_id：模型 ID（路径参数，必需）

响应字段说明

id：模型 ID
object：值为 "model"
created：模型创建时间戳
owned_by：模型所有者

代码示例

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())

异常处理说明

401 Unauthorized：API Key 无效或已过期
403 Forbidden：API Key 没有足够的权限
404 Not Found：模型不存在
500 Internal Server Error：服务器内部错误

账户余额查询接口

接口用途

查询当前账户的可用余额。

请求方式

方法：GET
URL：https://api.xftoken.ctclouds.com/v1/account/balance
认证：需要 API Key

请求参数

无

响应字段说明

balance：账户可用余额
currency：货币类型，默认 USD
updated_at：余额更新时间

代码示例

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())

异常处理说明

401 Unauthorized：API Key 无效或已过期
403 Forbidden：API Key 没有足够的权限
500 Internal Server Error：服务器内部错误