智涯千问AI开放平台

快速开始

获取API密钥

在仪表盘中申请API密钥，用于身份认证

选择SDK

根据您的开发语言选择合适的SDK

开始集成

参考文档示例，快速集成API功能

身份认证

智涯千问AI平台提供两种认证方式：短信验证码登录认证和JWT令牌认证。

POST /api/sms/send-code

发送短信验证码，用于用户登录认证。

请求参数

参数	类型	必填	描述
phone	string	是	11位手机号码

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"phone": "13800138000"}' \
  http://localhost:8030/api/sms/send-code

import requests

data = {
    'phone': '13800138000'
}

response = requests.post(
    'http://localhost:8030/api/sms/send-code',
    json=data
)

print(response.json())

const response = await fetch('http://localhost:8030/api/sms/send-code', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        phone: '13800138000'
    })
});

const result = await response.json();
console.log(result);

响应示例

{
  "success": true,
  "message": "验证码发送成功",
  "daily_remaining": 9,
  "hourly_remaining": 4
}

POST /api/sms/login

使用短信验证码登录，获取JWT访问令牌。

请求参数

参数	类型	必填	描述
phone	string	是	11位手机号码
code	string	是	6位短信验证码

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"phone": "13800138000", "code": "123456"}' \
  http://localhost:8030/api/sms/login

import requests

data = {
    'phone': '13800138000',
    'code': '123456'
}

response = requests.post(
    'http://localhost:8030/api/sms/login',
    json=data
)

print(response.json())

const response = await fetch('http://localhost:8030/api/sms/login', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        phone: '13800138000',
        code: '123456'
    })
});

const result = await response.json();
console.log(result);

响应示例

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "username": "user_13800138000",
    "email": "13800138000@example.com",
    "phone": "13800138000",
    "role": "user"
  }
}

HEADER Authorization: Bearer YOUR_ACCESS_TOKEN

在请求头中添加Authorization字段，值为"Bearer "加上您的访问令牌。

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello"}' \
  http://localhost:8030/api/unified/call

import requests

headers = {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

data = {
    'message': 'Hello'
}

response = requests.post(
    'http://localhost:8030/api/unified/call',
    headers=headers,
    json=data
)

const response = await fetch('http://localhost:8030/api/unified/call', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        message: 'Hello'
    })
});

对话API

POST /api/v1/chat/completions

智能对话接口，支持多轮对话和上下文管理。

请求参数

参数	类型	必填	描述
messages	array	是	对话消息数组
model	string	否	使用的模型名称
max_tokens	integer	否	最大生成token数
temperature	float	否	生成温度（0-1）

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "你好，请介绍一下自己"}
    ],
    "model": "gpt-4",
    "max_tokens": 1000,
    "temperature": 0.7
  }' \
  https://api.zyqw.com/v1/chat/completions

响应示例

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "你好！我是智涯千问AI助手..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

图像API

POST /api/v1/images/generate

根据文本描述生成高质量图像。

请求参数

参数	类型	必填	描述
prompt	string	是	图像生成提示词
size	string	否	图像尺寸（256x256, 512x512, 1024x1024）
quality	string	否	图像质量（standard, hd）

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只可爱的猫咪在花园里玩耍",
    "size": "1024x1024",
    "quality": "hd"
  }' \
  http://localhost:8030/api/generate/image

响应示例

{
  "success": true,
  "image_url": "https://example.com/images/generated-123.jpg",
  "prompt": "一只可爱的猫咪在花园里玩耍",
  "size": "1024x1024",
  "quality": "hd",
  "generation_time": 2.5
}

统一API网关

智涯千问AI平台提供统一的API网关，支持多种AI服务和数据服务调用。

POST /api/unified/call

调用统一服务接口，支持AI对话、数据查询、云服务等多种功能。

请求参数

参数	类型	必填	描述
service_type	string	是	服务类型：ai/data/cloud
provider	string	是	服务提供商：openai/tencent/aliyun/juhe
endpoint	string	是	具体的API端点
data	object	是	请求数据

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_type": "ai",
    "provider": "openai",
    "endpoint": "chat/completions",
    "data": {
      "model": "gpt-3.5-turbo",
      "messages": [
        {"role": "user", "content": "Hello, how are you?"}
      ]
    }
  }' \
  http://localhost:8030/api/unified/call

响应示例

{
  "success": true,
  "data": {
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "model": "gpt-3.5-turbo",
    "choices": [{
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I'm doing well, thank you for asking. How can I help you today?"
      },
      "finish_reason": "stop"
    }]
  },
  "provider": "openai",
  "execution_time": 0.45
}

POST /api/unified/aggregate

数据聚合API，支持从多个数据源聚合查询结果。

请求参数

参数	类型	必填	描述
queries	array	是	查询配置数组
aggregation_strategy	string	否	聚合策略：merge/priority/weighted

curl -X POST \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "service_type": "data",
        "provider": "juhe",
        "endpoint": "weather/query",
        "data": {"city": "北京"}
      },
      {
        "service_type": "data",
        "provider": "tencent",
        "endpoint": "weather/current",
        "data": {"city": "北京"}
      }
    ],
    "aggregation_strategy": "merge"
  }' \
  http://localhost:8030/api/unified/aggregate

响应示例

{
  "success": true,
  "data": {
    "juhe": {
      "city": "北京",
      "weather": "晴",
      "temperature": "25℃"
    },
    "tencent": {
      "city": "北京",
      "weather": "晴转多云",
      "temperature": "26℃",
      "humidity": "45%"
    }
  },
  "aggregated": {
    "city": "北京",
    "weather": "晴转多云",
    "temperature": "25-26℃",
    "humidity": "45%"
  }
}

错误代码

智涯千问AI平台使用标准HTTP状态码和自定义错误代码来标识API调用中的错误情况。

HTTP状态码标准HTTP状态码

常见HTTP状态码

状态码	描述	含义
200	OK	请求成功
400	Bad Request	请求参数错误
401	Unauthorized	未授权访问
403	Forbidden	禁止访问
404	Not Found	资源不存在
429	Too Many Requests	请求频率超限
500	Internal Server Error	服务器内部错误
503	Service Unavailable	服务不可用

错误代码自定义错误代码

自定义错误代码列表

错误代码	HTTP状态码	描述	解决方案
AUTH_001	401	访问令牌无效或已过期	重新获取访问令牌
AUTH_002	403	权限不足	检查用户权限设置
VALID_001	400	请求参数格式错误	检查请求参数格式
VALID_002	400	必填参数缺失	补充必填参数
RATE_001	429	API调用频率超限	降低调用频率或升级套餐
RATE_002	429	并发请求数超限	减少并发请求数
SERVICE_001	503	服务暂时不可用	稍后重试
SERVICE_002	500	内部服务错误	联系技术支持
QUOTA_001	403	配额不足	升级套餐或等待配额重置

错误响应示例

{
  "success": false,
  "error": {
    "code": "AUTH_001",
    "message": "访问令牌无效或已过期",
    "details": "Token expired at 2024-01-01T12:00:00Z",
    "timestamp": "2024-01-01T12:00:01Z"
  }
}

SDK支持

智涯千问AI平台提供多种编程语言的SDK，方便开发者快速集成API功能。

Python SDK

适用于Python开发者的官方SDK，支持异步调用和类型提示。

v1.0.0 查看文档

pip install zhiyai-sdk

JavaScript SDK

适用于Node.js和浏览器的SDK，支持Promise和TypeScript。

v1.0.0 查看文档

npm install zhiyai-sdk

Java SDK

适用于Java应用的SDK，支持Spring Boot集成。

v1.0.0 查看文档

<dependency>
    <groupId>com.zhiyai</groupId>
    <artifactId>sdk</artifactId>
    <version>1.0.0</version>
</dependency>

Go SDK

适用于Go语言的SDK，支持并发安全和上下文控制。

v1.0.0 查看文档

go get github.com/zhiyai/sdk

SDK特性核心功能特性

SDK核心特性

特性	描述	支持语言
自动重试	网络异常时自动重试，提高调用成功率	Python, JavaScript, Java, Go
请求限流	内置请求频率控制，避免超限错误	Python, JavaScript, Java, Go
异步支持	支持异步/非阻塞调用，提高性能	Python, JavaScript, Go
类型安全	完整的类型定义，减少运行时错误	Python, JavaScript, Java, Go
错误处理	统一的错误处理机制，便于调试	Python, JavaScript, Java, Go
日志记录	详细的请求日志，便于问题排查	Python, JavaScript, Java, Go

最佳实践

以下是一些API使用的最佳实践建议，帮助您构建稳定、高效的应用程序。

🔒安全实践

保护API密钥高
使用HTTPS 高
定期轮换密钥中
最小权限原则中

确保API调用的安全性，防止数据泄露和未授权访问。

⚡性能优化

批量处理显著
异步调用显著
缓存策略显著
连接复用中等

优化API调用性能，提高应用程序的响应速度和用户体验。

🛡️错误处理

指数退避重试 3-5次
错误分类处理分类
超时设置 30-60秒
错误日志记录详细

完善的错误处理机制，确保应用程序的稳定性和可维护性。

📊监控告警

错误率监控 >5%
响应时间监控 >2秒
配额使用率 >80%
并发连接数 >90%

实时监控API使用情况，及时发现问题并采取相应措施。

版本控制

智涯千问AI平台采用语义化版本控制，确保API的稳定性和向后兼容性。

版本策略

主版本 vX.0.0 不兼容

次版本 vX.Y.0 兼容

修订版本 vX.Y.Z 兼容

弃用策略

公告期 3个月警告

过渡期 6个月迁移

终止期 3个月停止

版本指定

URL路径 /api/v1/chat 最高

查询参数 ?version=v1 中等

请求头 X-API-Version 最低

API文档

快速导航

SDK支持

快速开始

获取API密钥

选择SDK

开始集成

身份认证

对话API

图像API

统一API网关

错误代码

SDK支持

Python SDK

JavaScript SDK

Java SDK

Go SDK

最佳实践

🔒安全实践

⚡性能优化

🛡️错误处理

📊监控告警

版本控制

版本策略

弃用策略

版本指定

快速入门

常见问题

高级功能