叶动文档中心叶动文档中心
叶动官网
使用指南
接口文档
  • 简体中文
  • English
GitHub
叶动官网
使用指南
接口文档
  • 简体中文
  • English
GitHub
  • 🌏 使用指南

    • 叶动历史小记
    • AutoBox 快速入门指南
    • API_KEY 客户端配置指南
    • 版本发布
    • 设计开发指南

API_KEY 客户端配置指南

概述

本文档详细介绍了如何在各种客户端环境中配置和使用 AutoBox API_KEY,包括网页应用、浏览器插件、移动客户端以及第三方应用的集成方式。

配置前准备

在开始配置之前,请确保您已经:

  1. 获得有效的 API_KEY

    • 登录 AutoBox 控制台
    • 创建并复制您的 API_KEY
    • 确认 API_KEY 状态为"启用"
  2. 了解基本信息

    • API 基础 URL: https://your-domain.com/v1
    • 认证方式: Bearer Token
    • API_KEY 格式: ak- + 32位字符
  3. 检查网络环境

    • 确保客户端可以访问 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 有效性

故障排除

常见配置问题

  1. API_KEY 无效

    • 检查 API_KEY 格式是否正确
    • 确认 API_KEY 状态为"启用"
    • 验证 API_KEY 是否过期
  2. 网络连接问题

    • 检查防火墙设置
    • 验证代理配置
    • 确认 DNS 解析正常
  3. 请求格式错误

    • 检查请求头格式
    • 验证请求体 JSON 格式
    • 确认参数类型和值
  4. 权限问题

    • 检查用户账户状态
    • 验证 API_KEY 权限范围
    • 确认配额是否充足

调试技巧

  1. 启用详细日志
  2. 使用网络抓包工具
  3. 测试简单请求
  4. 检查响应头信息
  5. 对比工作正常的配置

最佳实践总结

  1. 安全第一: 永远不要在客户端暴露 API_KEY
  2. 环境分离: 为不同环境使用不同的 API_KEY
  3. 监控告警: 实时监控 API 使用情况
  4. 错误处理: 实现完善的错误处理机制
  5. 性能优化: 使用连接池和缓存机制
  6. 定期维护: 定期更新和轮换 API_KEY

通过遵循本指南,您可以在各种客户端环境中成功配置和使用 AutoBox API_KEY。如有问题,请参考错误码文档或联系技术支持。

在 GitHub 上编辑此页
Prev
AutoBox 快速入门指南
Next
版本发布