AutoBoxAPI 使用概述

简介

AutoBox提供了一套完整的 RESTful API 接口，支持多种任务类型的执行和管理。本文档将为您介绍如何使用 API_KEY 来调用我们的 v1 版本接口。

API 基础信息

  • 基础 URL: https://your-domain.com/v1
  • 认证方式: Bearer Token (API_KEY)
  • 数据格式: JSON
  • 字符编码: UTF-8

v1 接口主要构成

1. 任务执行接口

AutoBoxv1 API 支持四种主要的任务类型：

AutoBox 任务

  • 同步执行: POST /v1/autobox/{app_id}/sync
  • 异步执行: POST /v1/autobox/{app_id}/async
  • 功能: 支持轮询机制的智能任务处理

n8n 工作流任务

  • 同步执行: POST /v1/n8n/{app_id}/sync
  • 异步执行: POST /v1/n8n/{app_id}/async
  • 功能: 工作流自动化任务执行

Dify AI 应用任务

  • 同步执行: POST /v1/dify/{app_id}/sync
  • 异步执行: POST /v1/dify/{app_id}/async
  • 功能: AI 应用任务处理

Coze 对话机器人任务

  • 同步执行: POST /v1/coze/{app_id}/sync
  • 异步执行: POST /v1/coze/{app_id}/async
  • 功能: 对话机器人任务执行

2. 任务管理接口

任务状态更新

  • 单个更新: POST /v1/task-status/update
  • 批量更新: POST /v1/task-status/batch-update

任务查询

  • 单个查询: GET /v1/task-query/{task_number}
  • 批量查询: POST /v1/task-query/batch
  • 列表查询: POST /v1/task-query/list

调用方式

1. 认证头设置

所有 API 请求都需要在请求头中包含您的 API_KEY：

Authorization: Bearer your_api_key_here
Content-Type: application/json

2. 基本请求格式

同步任务执行示例

POST /v1/autobox/your_app_id/sync
Authorization: Bearer ak-your32characterapikeyhere
Content-Type: application/json

{
  "messages": [
    {"role": "user", "content": "Hello, world!"}
  ],
  "model": "gpt-3.5-turbo",
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 100,
  "app_id": "your_app_id",
  "call_params": {
    "custom_param": "value"
  }
}

异步任务执行示例

POST /v1/autobox/your_app_id/async
Authorization: Bearer ak-your32characterapikeyhere
Content-Type: application/json

{
  "messages": [
    {"role": "user", "content": "Process this data"}
  ],
  "model": "gpt-4",
  "stream": false,
  "app_id": "your_app_id"
}

3. 响应格式

成功响应

{
  "id": "chatcmpl-abc123def456ghi789",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-3.5-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

错误响应

{
  "detail": "API Key验证失败：无效的API Key"
}

支持的参数

通用参数

参数名类型必填描述
messagesarray是消息数组，包含角色和内容
modelstring否使用的模型名称，默认为 gpt-3.5-turbo
streamboolean否是否启用流式响应，默认为 false
temperaturenumber否温度参数，控制随机性，范围 0-2
max_tokensnumber否最大生成令牌数
app_idstring是应用ID
call_paramsobject否自定义调用参数

消息格式

{
  "role": "user|assistant|system",
  "content": "消息内容"
}

任务状态说明

状态描述
等待中任务已提交，等待处理
执行中任务正在执行
已完成任务执行成功
已报错任务执行失败
已取消任务被取消

流式响应

当 stream 参数设置为 true 时，API 将返回流式响应：

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"gpt-3.5-turbo","choices":[{"index":0,"delta":{"content":" there"},"finish_reason":null}]}

data: [DONE]

速率限制

  • 每个 API_KEY 都有相应的配额限制
  • 超出配额后将返回 429 错误
  • 建议实现指数退避重试机制

最佳实践

  1. 错误处理: 始终检查响应状态码和错误信息
  2. 重试机制: 对于网络错误和服务器错误实现重试
  3. 配额管理: 监控 API 使用量，避免超出限制
  4. 安全性: 妥善保管 API_KEY，不要在客户端代码中暴露
  5. 异步处理: 对于长时间运行的任务，建议使用异步接口

下一步