开发文档
欢迎使用TIFA AI API。本文档将指导您如何接入和使用我们的服务。TIFA AI提供强大的自然语言处理能力，支持多种场景应用。
当前版本：v1.0
最后更新：2024-03-20
主要特性
- ✨ 支持流式输出，实时响应
- ✨ 超长上下文支持，最大支持100K tokens
- ✨ 多语言支持，支持中英日韩等40+种语言
- ✨ 99.9%的服务可用性保证
认证方式
所有API请求都需要使用API密钥进行认证。您可以在控制台获取API密钥。
⚠️ 请妥善保管您的API密钥，不要在客户端代码中明文存储。
注意事项：
- API密钥具有完整的账户权限，请勿泄露
- 建议使用环境变量或配置文件存储API密钥
- 定期轮换API密钥以提升安全性
- 可以为不同应用创建不同的API密钥
使用限制
为了保证服务质量，API访问有以下限制：
- 每个API密钥每分钟最多60次请求
- 单次请求最大输入4000 tokens
- 每月总使用量根据套餐不同有所限制
💡 如需更高配额，请联系商务团队升级套餐
最佳实践
1. 错误处理
- 实现完善的错误处理机制
- 对网络错误进行重试
- 设置合理的超时时间
- 记录详细的错误日志
2. 性能优化
- 使用连接池复用连接
- 启用gzip压缩
- 实现请求缓存
- 采用异步处理方式
3. 安全建议
- 使用环境变量存储密钥
- 启用HTTPS传输
- 实现请求签名机制
- 定期更新API密钥
4. 开发建议
- 使用SDK而非直接调用API
- 做好开发环境与生产环境隔离
- 合理设置模型参数
- 实现优雅的降级机制
💡 这些最佳实践将帮助您构建更稳定可靠的应用
API Endpoint
POST http://visionsic.com:8001/v1/chat/completions请求说明：
- 仅支持HTTPS协议
- 请求体必须是JSON格式
- 响应编码为UTF-8
- 支持跨域请求(CORS)
示例代码
import requests
import json
url = "http://visionsic.com:8001/v1/chat/completions"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_KEY"
}
data = {
"model": "/home/fangxin/claude",
"messages": [
{"role": "system", "content": "你是一个助手"},
{"role": "user", "content": "你好"}
],
"temperature": 0.4,
"stream": True
}
# 错误处理
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status() # 检查HTTP错误
for line in response.iter_lines():
if line:
print(json.loads(line))
except requests.exceptions.RequestException as e:
print(f"API请求错误: {e}")
except json.JSONDecodeError as e:
print(f"JSON解析错误: {e}")
const url = 'http://visionsic.com:8001/v1/chat/completions';
const headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
};
const data = {
model: '/home/fangxin/claude',
messages: [
{role: 'system', content: '你是一个助手'},
{role: 'user', content: '你好'}
],
temperature: 0.4,
stream: true
};
// 使用async/await和错误处理
async function chatWithAI() {
try {
const response = await fetch(url, {
method: 'POST',
headers: headers,
body: JSON.stringify(data)
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const result = await response.json();
console.log(result);
} catch (error) {
console.error('请求错误:', error);
}
}
chatWithAI();
# 基本请求
curl -X POST http://visionsic.com:8001/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "/home/fangxin/claude",
"messages": [
{"role": "system", "content": "你是一个助手"},
{"role": "user", "content": "你好"}
],
"temperature": 0.4,
"stream": true
}'
# 带超时设置的请求
curl -X POST http://visionsic.com:8001/v1/chat/completions \
--connect-timeout 10 \
--max-time 30 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d @request.json
代码说明：
- 示例中包含了基本的错误处理
- 建议在生产环境中添加重试机制
- 可以根据需要调整超时设置
- stream模式下建议使用异步处理
对话接口
接口地址: http://visionsic.com:8001/v1/chat/completions
请求方式: POST
Content-Type: application/json
对话接口支持单轮和多轮对话,可以通过调整不同参数来控制AI的行为表现。支持流式输出和普通输出两种模式。
参数说明
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| model | string | 是 | 模型路径,例如"/home/fangxin/claude" |
| messages | array | 是 | 对话历史,包含role和content字段 |
| temperature | number | 否 | 温度参数,控制随机性,范围0-1,默认0.7 |
| stream | boolean | 否 | 是否启用流式输出,默认false |
| max_tokens | integer | 否 | 生成文本的最大长度,默认2048 |
返回格式:
{
"id": "chat_12345678",
"object": "chat.completion",
"created": 1679478935,
"model": "/home/fangxin/claude",
"choices": [{
"message": {
"role": "assistant",
"content": "AI的回复内容"
},
"finish_reason": "stop",
"index": 0
}]
}
错误处理
常见错误码：
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| 401 | 未授权 | 检查API密钥是否正确 |
| 429 | 请求过于频繁 | 实现请求限流 |
| 500 | 服务器错误 | 稍后重试或联系支持 |
高级功能
1. 流式输出
支持实时流式返回AI响应,提供更好的交互体验。
// 启用流式输出
const response = await fetch(url, {
method: 'POST',
headers: headers,
body: JSON.stringify({...data, stream: true})
});
const reader = response.body.getReader();
while(true) {
const {done, value} = await reader.read();
if (done) break;
console.log(new TextDecoder().decode(value));
}
2. 函数调用
支持自定义函数能力,扩展AI助手的功能范围。
const functions = [{
"name": "get_weather",
"description": "获取天气信息",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市名称"
}
}
}
}];
const response = await fetch(url, {
method: 'POST',
headers: headers,
body: JSON.stringify({
...data,
functions: functions,
function_call: "auto"
})
});
3. 上下文记忆
支持多轮对话记忆,实现连贯的对话体验。
const messages = [
{"role": "system", "content": "你是一个助手"},
{"role": "user", "content": "今天天气怎么样?"},
{"role": "assistant", "content": "北京今天晴朗"},
{"role": "user", "content": "温度呢?"} // 延续上下文
];
4. 模型参数调优
提供丰富的参数配置,实现个性化的输出控制。
- temperature: 控制输出随机性 (0-1)
- top_p: 控制输出多样性
- max_tokens: 控制输出长度
- presence_penalty: 控制话题新鲜度
💡 高级功能可能需要更高级别的API权限,请联系客服升级