API_KEY 客户端配置指南
概述
本文档详细介绍了如何在各种客户端环境中配置和使用 AutoBox API_KEY,包括网页应用、浏览器插件、移动客户端以及第三方应用的集成方式。
配置前准备
在开始配置之前,请确保您已经:
获得有效的 API_KEY
- 登录 AutoBox 控制台
- 创建并复制您的 API_KEY
- 确认 API_KEY 状态为"启用"
了解基本信息
- API 基础 URL:
https://your-domain.com/v1 - 认证方式: Bearer Token
- API_KEY 格式:
ak-+ 32位字符
- API 基础 URL:
检查网络环境
- 确保客户端可以访问 AutoBox 服务器
- 检查防火墙和代理设置
网页应用配置
1. 前端 JavaScript 配置
基础配置
// 配置文件 config.js
const AutoBoxConfig = {
apiKey: 'ak-your32characterapikeyhere',
baseUrl: 'https://your-domain.com/v1',
timeout: 30000, // 30秒超时
retryAttempts: 3
};
// API 客户端类
class AutoBoxWebClient {
constructor(config = AutoBoxConfig) {
this.apiKey = config.apiKey;
this.baseUrl = config.baseUrl;
this.timeout = config.timeout;
this.retryAttempts = config.retryAttempts;
}
async request(endpoint, options = {}) {
const url = `${this.baseUrl}${endpoint}`;
const headers = {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json',
...options.headers
};
const fetchOptions = {
method: 'POST',
headers,
...options
};
try {
const response = await fetch(url, fetchOptions);
if (!response.ok) {
const error = await response.json();
throw new Error(error.detail || '请求失败');
}
return await response.json();
} catch (error) {
console.error('API请求失败:', error);
throw error;
}
}
}
// 使用示例
const client = new AutoBoxWebClient();
// 调用 API
client.request('/autobox/your_app_id/sync', {
body: JSON.stringify({
messages: [{ role: 'user', content: 'Hello' }],
model: 'gpt-3.5-turbo'
})
}).then(result => {
console.log('响应:', result);
}).catch(error => {
console.error('错误:', error);
});
环境变量配置
// 使用环境变量(适用于 React、Vue 等框架)
const config = {
apiKey: process.env.REACT_APP_AutoBox_API_KEY,
baseUrl: process.env.REACT_APP_AutoBox_BASE_URL || 'https://your-domain.com/v1'
};
// .env 文件
REACT_APP_AutoBox_API_KEY=ak-your32characterapikeyhere
REACT_APP_AutoBox_BASE_URL=https://your-domain.com/v1
安全配置建议
// 使用代理服务器隐藏 API_KEY
const ProxyClient = {
async callAPI(endpoint, data) {
// 通过后端代理调用,避免在前端暴露 API_KEY
const response = await fetch('/api/proxy/AutoBox', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({
endpoint,
data
})
});
return await response.json();
}
};
2. Node.js 后端配置
// package.json 依赖
{
"dependencies": {
"axios": "^1.6.0",
"dotenv": "^16.3.1"
}
}
// .env 文件
AutoBox_API_KEY=ak-your32characterapikeyhere
AutoBox_BASE_URL=https://your-domain.com/v1
// 配置文件 AutoBox.js
require('dotenv').config();
const axios = require('axios');
class AutoBoxClient {
constructor() {
this.apiKey = process.env.AutoBox_API_KEY;
this.baseUrl = process.env.AutoBox_BASE_URL;
if (!this.apiKey) {
throw new Error('AutoBox_API_KEY 环境变量未设置');
}
this.client = axios.create({
baseURL: this.baseUrl,
timeout: 30000,
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
}
});
// 请求拦截器
this.client.interceptors.request.use(
config => {
console.log(`发送请求: ${config.method.toUpperCase()} ${config.url}`);
return config;
},
error => Promise.reject(error)
);
// 响应拦截器
this.client.interceptors.response.use(
response => response.data,
error => {
console.error('API请求失败:', error.response?.data || error.message);
return Promise.reject(error);
}
);
}
async chatCompletion(appId, messages, options = {}) {
return await this.client.post(`/autobox/${appId}/sync`, {
messages,
model: 'gpt-3.5-turbo',
...options
});
}
}
module.exports = AutoBoxClient;
浏览器插件配置
1. Chrome 扩展配置
manifest.json
{
"manifest_version": 3,
"name": "AutoBox Assistant",
"version": "1.0.0",
"description": "AutoBox API 集成插件",
"permissions": [
"storage",
"activeTab"
],
"host_permissions": [
"https://your-domain.com/*"
],
"background": {
"service_worker": "background.js"
},
"content_scripts": [
{
"matches": ["<all_urls>"],
"js": ["content.js"]
}
],
"action": {
"default_popup": "popup.html",
"default_title": "AutoBox Assistant"
}
}
background.js
// 后台脚本
class AutoBoxExtension {
constructor() {
this.apiKey = null;
this.baseUrl = 'https://your-domain.com/v1';
this.loadConfig();
}
async loadConfig() {
const result = await chrome.storage.sync.get(['apiKey', 'baseUrl']);
this.apiKey = result.apiKey;
this.baseUrl = result.baseUrl || this.baseUrl;
}
async saveConfig(apiKey, baseUrl) {
await chrome.storage.sync.set({
apiKey: apiKey,
baseUrl: baseUrl
});
this.apiKey = apiKey;
this.baseUrl = baseUrl;
}
async callAPI(endpoint, data) {
if (!this.apiKey) {
throw new Error('API Key 未配置');
}
const response = await fetch(`${this.baseUrl}${endpoint}`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(data)
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.detail || '请求失败');
}
return await response.json();
}
}
const AutoBox = new AutoBoxExtension();
// 监听来自 popup 和 content script 的消息
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
if (request.action === 'callAPI') {
AutoBox.callAPI(request.endpoint, request.data)
.then(result => sendResponse({ success: true, data: result }))
.catch(error => sendResponse({ success: false, error: error.message }));
return true; // 保持消息通道开放
}
});
popup.html 和 popup.js
<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<style>
body { width: 300px; padding: 20px; }
.form-group { margin-bottom: 15px; }
label { display: block; margin-bottom: 5px; }
input { width: 100%; padding: 8px; border: 1px solid #ddd; border-radius: 4px; }
button { background: #007cba; color: white; padding: 10px 20px; border: none; border-radius: 4px; cursor: pointer; }
button:hover { background: #005a87; }
.status { margin-top: 10px; padding: 10px; border-radius: 4px; }
.success { background: #d4edda; color: #155724; }
.error { background: #f8d7da; color: #721c24; }
</style>
</head>
<body>
<h3>AutoBox 配置</h3>
<div class="form-group">
<label for="apiKey">API Key:</label>
<input type="password" id="apiKey" placeholder="ak-your32characterapikeyhere">
</div>
<div class="form-group">
<label for="baseUrl">Base URL:</label>
<input type="text" id="baseUrl" placeholder="https://your-domain.com/v1">
</div>
<button id="saveConfig">保存配置</button>
<button id="testAPI">测试连接</button>
<div id="status"></div>
<script src="popup.js"></script>
</body>
</html>
// popup.js
document.addEventListener('DOMContentLoaded', async () => {
// 加载已保存的配置
const result = await chrome.storage.sync.get(['apiKey', 'baseUrl']);
if (result.apiKey) {
document.getElementById('apiKey').value = result.apiKey;
}
if (result.baseUrl) {
document.getElementById('baseUrl').value = result.baseUrl;
}
// 保存配置
document.getElementById('saveConfig').addEventListener('click', async () => {
const apiKey = document.getElementById('apiKey').value;
const baseUrl = document.getElementById('baseUrl').value || 'https://your-domain.com/v1';
if (!apiKey) {
showStatus('请输入 API Key', 'error');
return;
}
await chrome.storage.sync.set({ apiKey, baseUrl });
showStatus('配置已保存', 'success');
});
// 测试 API 连接
document.getElementById('testAPI').addEventListener('click', async () => {
const apiKey = document.getElementById('apiKey').value;
const baseUrl = document.getElementById('baseUrl').value || 'https://your-domain.com/v1';
if (!apiKey) {
showStatus('请先输入 API Key', 'error');
return;
}
try {
showStatus('测试连接中...', '');
const response = await chrome.runtime.sendMessage({
action: 'callAPI',
endpoint: '/autobox/test/sync',
data: {
messages: [{ role: 'user', content: 'test' }],
model: 'gpt-3.5-turbo'
}
});
if (response.success) {
showStatus('连接测试成功', 'success');
} else {
showStatus(`连接测试失败: ${response.error}`, 'error');
}
} catch (error) {
showStatus(`连接测试失败: ${error.message}`, 'error');
}
});
function showStatus(message, type) {
const statusDiv = document.getElementById('status');
statusDiv.textContent = message;
statusDiv.className = `status ${type}`;
if (type === 'success') {
setTimeout(() => {
statusDiv.textContent = '';
statusDiv.className = 'status';
}, 3000);
}
}
});
2. Firefox 扩展配置
Firefox 扩展的配置与 Chrome 类似,主要区别在于:
// manifest.json (Firefox)
{
"manifest_version": 2,
"name": "AutoBox Assistant",
"version": "1.0.0",
"description": "AutoBox API 集成插件",
"permissions": [
"storage",
"activeTab",
"https://your-domain.com/*"
],
"background": {
"scripts": ["background.js"],
"persistent": false
},
"content_scripts": [
{
"matches": ["<all_urls>"],
"js": ["content.js"]
}
],
"browser_action": {
"default_popup": "popup.html",
"default_title": "AutoBox Assistant"
}
}
移动客户端配置
1. iOS 应用配置
Swift 配置示例
// AutoBoxConfig.swift
import Foundation
struct AutoBoxConfig {
static let shared = AutoBoxConfig()
private let apiKey: String
private let baseUrl: String
private init() {
// 从 Info.plist 或 Keychain 读取配置
guard let path = Bundle.main.path(forResource: "Config", ofType: "plist"),
let config = NSDictionary(contentsOfFile: path) else {
fatalError("Config.plist not found")
}
self.apiKey = config["AutoBoxAPIKey"] as? String ?? ""
self.baseUrl = config["AutoBoxBaseURL"] as? String ?? "https://your-domain.com/v1"
}
func getAPIKey() -> String {
return apiKey
}
func getBaseURL() -> String {
return baseUrl
}
}
// AutoBoxClient.swift
import Foundation
class AutoBoxClient {
private let config = AutoBoxConfig.shared
private let session = URLSession.shared
func chatCompletion(appId: String, messages: [[String: String]], completion: @escaping (Result<[String: Any], Error>) -> Void) {
guard let url = URL(string: "\(config.getBaseURL())/autobox/\(appId)/sync") else {
completion(.failure(NSError(domain: "InvalidURL", code: 0, userInfo: nil)))
return
}
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("Bearer \(config.getAPIKey())", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
let requestBody: [String: Any] = [
"messages": messages,
"model": "gpt-3.5-turbo"
]
do {
request.httpBody = try JSONSerialization.data(withJSONObject: requestBody)
} catch {
completion(.failure(error))
return
}
session.dataTask(with: request) { data, response, error in
if let error = error {
completion(.failure(error))
return
}
guard let data = data else {
completion(.failure(NSError(domain: "NoData", code: 0, userInfo: nil)))
return
}
do {
let json = try JSONSerialization.jsonObject(with: data) as? [String: Any]
completion(.success(json ?? [:]))
} catch {
completion(.failure(error))
}
}.resume()
}
}
Config.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>AutoBoxAPIKey</key>
<string>ak-your32characterapikeyhere</string>
<key>AutoBoxBaseURL</key>
<string>https://your-domain.com/v1</string>
</dict>
</plist>
2. Android 应用配置
Java/Kotlin 配置示例
// AutoBoxConfig.kt
object AutoBoxConfig {
private const val PREFS_NAME = "AutoBox_config"
private const val API_KEY = "api_key"
private const val BASE_URL = "base_url"
private const val DEFAULT_BASE_URL = "https://your-domain.com/v1"
fun saveConfig(context: Context, apiKey: String, baseUrl: String = DEFAULT_BASE_URL) {
val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
prefs.edit()
.putString(API_KEY, apiKey)
.putString(BASE_URL, baseUrl)
.apply()
}
fun getApiKey(context: Context): String? {
val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
return prefs.getString(API_KEY, null)
}
fun getBaseUrl(context: Context): String {
val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
return prefs.getString(BASE_URL, DEFAULT_BASE_URL) ?: DEFAULT_BASE_URL
}
}
// AutoBoxClient.kt
import okhttp3.*
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.RequestBody.Companion.toRequestBody
import org.json.JSONObject
import org.json.JSONArray
import java.io.IOException
class AutoBoxClient(private val context: Context) {
private val client = OkHttpClient()
private val mediaType = "application/json; charset=utf-8".toMediaType()
fun chatCompletion(
appId: String,
messages: List<Map<String, String>>,
callback: (Result<String>) -> Unit
) {
val apiKey = AutoBoxConfig.getApiKey(context)
val baseUrl = AutoBoxConfig.getBaseUrl(context)
if (apiKey == null) {
callback(Result.failure(Exception("API Key not configured")))
return
}
val url = "$baseUrl/autobox/$appId/sync"
val requestBody = JSONObject().apply {
put("messages", JSONArray(messages))
put("model", "gpt-3.5-turbo")
}
val request = Request.Builder()
.url(url)
.post(requestBody.toString().toRequestBody(mediaType))
.addHeader("Authorization", "Bearer $apiKey")
.addHeader("Content-Type", "application/json")
.build()
client.newCall(request).enqueue(object : Callback {
override fun onFailure(call: Call, e: IOException) {
callback(Result.failure(e))
}
override fun onResponse(call: Call, response: Response) {
response.use {
if (!response.isSuccessful) {
callback(Result.failure(Exception("HTTP ${response.code}")))
return
}
val responseBody = response.body?.string()
if (responseBody != null) {
callback(Result.success(responseBody))
} else {
callback(Result.failure(Exception("Empty response")))
}
}
}
})
}
}
build.gradle 依赖
dependencies {
implementation 'com.squareup.okhttp3:okhttp:4.12.0'
implementation 'org.json:json:20230227'
}
第三方应用集成
1. Postman 配置
环境变量设置
{
"name": "AutoBox Environment",
"values": [
{
"key": "AutoBox_api_key",
"value": "ak-your32characterapikeyhere",
"type": "secret"
},
{
"key": "AutoBox_base_url",
"value": "https://your-domain.com/v1",
"type": "default"
},
{
"key": "app_id",
"value": "your_app_id",
"type": "default"
}
]
}
请求模板
{
"info": {
"name": "AutoBox API Collection",
"description": "AutoBox API 调用集合"
},
"item": [
{
"name": "AutoBox Sync",
"request": {
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "Bearer {{AutoBox_api_key}}"
},
{
"key": "Content-Type",
"value": "application/json"
}
],
"body": {
"mode": "raw",
"raw": "{\n \"messages\": [\n {\"role\": \"user\", \"content\": \"Hello\"}\n ],\n \"model\": \"gpt-3.5-turbo\",\n \"temperature\": 0.7\n}"
},
"url": {
"raw": "{{AutoBox_base_url}}/autobox/{{app_id}}/sync",
"host": ["{{AutoBox_base_url}}"],
"path": ["autobox", "{{app_id}}", "sync"]
}
}
}
]
}
2. Insomnia 配置
环境配置
{
"name": "AutoBox",
"data": {
"AutoBox_api_key": "ak-your32characterapikeyhere",
"AutoBox_base_url": "https://your-domain.com/v1",
"app_id": "your_app_id"
}
}
3. cURL 脚本配置
#!/bin/bash
# AutoBox API 配置
AutoBox_API_KEY="ak-your32characterapikeyhere"
AutoBox_BASE_URL="https://your-domain.com/v1"
APP_ID="your_app_id"
# 函数:调用 AutoBox API
call_autobox() {
local message="$1"
local model="${2:-gpt-3.5-turbo}"
curl -X POST "${AutoBox_BASE_URL}/autobox/${APP_ID}/sync" \
-H "Authorization: Bearer ${AutoBox_API_KEY}" \
-H "Content-Type: application/json" \
-d "{
\"messages\": [
{\"role\": \"user\", \"content\": \"${message}\"}
],
\"model\": \"${model}\",
\"temperature\": 0.7
}"
}
# 使用示例
call_autobox "Hello, AutoBox!"
配置验证和测试
1. 连接测试脚本
#!/usr/bin/env python3
import requests
import json
import sys
def test_AutoBox_connection(api_key, base_url, app_id):
"""测试 AutoBox API 连接"""
url = f"{base_url}/autobox/{app_id}/sync"
headers = {
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
}
payload = {
'messages': [
{'role': 'user', 'content': 'test connection'}
],
'model': 'gpt-3.5-turbo',
'max_tokens': 10
}
try:
print("正在测试连接...")
response = requests.post(url, headers=headers, json=payload, timeout=30)
if response.status_code == 200:
print("✅ 连接测试成功")
result = response.json()
print(f"响应: {result.get('choices', [{}])[0].get('message', {}).get('content', 'N/A')}")
return True
else:
print(f"❌ 连接测试失败: HTTP {response.status_code}")
print(f"错误信息: {response.text}")
return False
except requests.exceptions.RequestException as e:
print(f"❌ 连接测试失败: {e}")
return False
if __name__ == "__main__":
# 配置信息
API_KEY = "ak-your32characterapikeyhere"
BASE_URL = "https://your-domain.com/v1"
APP_ID = "your_app_id"
# 执行测试
success = test_AutoBox_connection(API_KEY, BASE_URL, APP_ID)
sys.exit(0 if success else 1)
2. 配置检查清单
在部署到生产环境之前,请检查以下项目:
安全检查
- [ ] API_KEY 未在客户端代码中硬编码
- [ ] 使用环境变量或安全存储管理 API_KEY
- [ ] 启用 HTTPS 连接
- [ ] 实现适当的错误处理,避免泄露敏感信息
功能检查
- [ ] API_KEY 格式正确(ak- + 32位字符)
- [ ] API_KEY 状态为"启用"
- [ ] 网络连接正常
- [ ] 请求头格式正确
- [ ] 请求体参数符合 API 规范
性能检查
- [ ] 设置合适的超时时间
- [ ] 实现重试机制
- [ ] 使用连接池优化性能
- [ ] 监控 API 调用频率和配额使用
监控检查
- [ ] 实现日志记录
- [ ] 监控错误率和响应时间
- [ ] 设置配额告警
- [ ] 定期检查 API_KEY 有效性
故障排除
常见配置问题
API_KEY 无效
- 检查 API_KEY 格式是否正确
- 确认 API_KEY 状态为"启用"
- 验证 API_KEY 是否过期
网络连接问题
- 检查防火墙设置
- 验证代理配置
- 确认 DNS 解析正常
请求格式错误
- 检查请求头格式
- 验证请求体 JSON 格式
- 确认参数类型和值
权限问题
- 检查用户账户状态
- 验证 API_KEY 权限范围
- 确认配额是否充足
调试技巧
- 启用详细日志
- 使用网络抓包工具
- 测试简单请求
- 检查响应头信息
- 对比工作正常的配置
最佳实践总结
- 安全第一: 永远不要在客户端暴露 API_KEY
- 环境分离: 为不同环境使用不同的 API_KEY
- 监控告警: 实时监控 API 使用情况
- 错误处理: 实现完善的错误处理机制
- 性能优化: 使用连接池和缓存机制
- 定期维护: 定期更新和轮换 API_KEY
通过遵循本指南,您可以在各种客户端环境中成功配置和使用 AutoBox API_KEY。如有问题,请参考错误码文档或联系技术支持。
