Skip to content

Create a New APICORE Configuration File

Jump to bottom
SRInternet edited this page Oct 3, 2025 · 7 revisions

创建 APICORE 规范的API配置文件

最近更新：2025年10月04日

写在前面

APICORE 配置文件编辑器 现已上线。访问我们的仓库并下载最新的 Release 或运行编辑器源代码，通过直观的图形化界面编写符合 APICORE 规范的API配置。

目录

  1. 配置文件结构概述

  2. 基本配置字段

  3. 参数配置详解

  4. 响应配置详解

  5. 完整示例

1. 配置文件结构概述

配置文件为JSON格式，文件扩展名为 .api.json ，包含以下主要部分：

{
    "friendly_name": "",
    "intro": "",
    "icon": "",
    "link": "",
    "func": "",
    "APICORE_version": "",
    "parameters": [],
    "response": {}
}
字段名 必需 数据类型 描述
friendly_name 是 字符串 API接口名称
intro 否 字符串 API接口简介
icon 否 字符串 API接口图标URL
link 是 字符串 API接口链接
func 是 字符串 HTTP请求方法 (GET, POST, PUT, DELETE等)
APICORE_version 是 字符串 使用的APICORE版本 (当前固定为"1.0")
parameters 是 数组 API请求参数配置列表
response 是 对象 API响应解析配置

2. 基本配置字段

friendly_name - API接口名称

  • 用于用户界面显示
  • 示例："API_EXAMPLE"

intro - API接口简介

  • 用于用户界面显示
  • 示例："示例 API 配置文件"

icon - API接口图标URL

  • 用于用户界面显示
  • 示例："https://github.com/user-attachments/assets/83078bfd-fb6a-4ffd-90b2-27bf7f611bf9"

link - API接口地址

  • 必须包含完整URL，包括协议 (http://或https://)
  • 示例："https://api.example.com/generate"

func - HTTP请求方法

  • 必须使用标准HTTP方法，全部大写
  • 示例："POST"

APICORE_version - 版本标识

  • 当前固定为"1.0"
  • 用于兼容性检查和未来版本升级

3. 参数配置详解

parameters是一个数组，包含多个参数配置对象：

"parameters": [
    {
        "enable": true, 
        "name": "",
        "type": "",
        "required": true,
        "value": null,
        "friendly_value": [],
        "friendly_name": "",
        "min_value": null,
        "max_value": null,
        "split_str": null
    }
]

参数对象字段说明

字段 必需 数据类型 描述
enable 否 布尔值 参数是否显示在用户界面上 (缺省值为true)
name 当HTTP请求方法不为 GET, HEAD 时 字符串 参数关键字
type 是 字符串 参数类型 (integer, boolean, list, string, enum)
required 否 布尔值 参数是否必需 (缺省值为true)
friendly_value enum类型必需 列表 参数的可选值在用户界面显示的友好名称 (类型为enum时)
value 是 类型相关 参数的默认值，参数的可选值 (类型为enum时)
friendly_name 是 字符串 参数在用户界面显示的友好名称
min_value integer类型必需 整数 最小值 (仅integer类型有效)
max_value integer类型必需 整数 最大值 (仅integer类型有效)
split_str list类型必需 字符串 列表分割符 (仅list类型有效)

参数特殊规则

  1. 当 enable 为 false 时，参数不会显示在用户界面上供用户修改。在请求时，会直接使用 value 内的值
  2. enable 在 type 为 enum 时无法生效，因为 enum 要求必须在列表中选择一个值，强行指定 enable 为 false 可能导致意外的错误
  3. 当API的HTTP请求方法是 GET 或 HEAD 时，参数 name 可以缺省，因为当HTTP请求方法为这二者时，会优先将所有参数填充到URL中
  4. 当参数 name 缺省时，其值会被直接追加到 link 后面。如：
    "link": "https://image.pollinations.ai/prompt/",
    "func": "GET",
    "APICORE_version": "1.0",
    "parameters": [
      {
        "type": "string",
        "value": "beautiful_girl",
        "required": false,
        "friendly_name": "描述你的图片（英语）",
        "min_value": null,
        "max_value": null,
        "split_str": null
      },
      {
        "name": "nologo",
        "type": "enum",
        "required": true,
        "value": ["true", "false"],
        "friendly_value": ["不包含", "包含"],
        "friendly_name": "正版水印",
        "min_value": null,
        "max_value": null,
        "split_str": null
      }
    ]

生成时使用填充后的URL：https://image.pollinations.ai/prompt/beautiful_girl?nologo=true

  1. required 的作用是判断当此参数的用户输入为空时，是否仍要将空值传递给接口
  2. split_str 当HTTP请求方法是 GET 或 HEAD 时，如何在URL中填充每个值并加以区分。如当参数 tag 的 split_str 为 | 时，填充后的URL：https://api.lolicon.app/setu/v2?tag=girl|cute|smile

不同参数类型的配置要求

integer(整数)

{
    "name": "",
    "type": "integer",
    "required": true,
    "value": 5,
    "friendly_name": "生成数量",
    "min_value": 1,
    "max_value": 10,
    "split_str": null
}

boolean(布尔值)

{
    "name": "",
    "type": "boolean",
    "required": true,
    "value": false,
    "friendly_name": "年龄是否大于20",
    "min_value": null,
    "max_value": null,
    "split_str": null
}

list(列表)

{
    "name": "",
    "type": "list",
    "required": true,
    "value": ["apple", "banana", "orange"],
    "friendly_name": "水果选择",
    "min_value": null,
    "max_value": null,
    "split_str": "&"
}

string(字符串)

{
    "name": "",
    "type": "string",
    "required": false,
    "value": "SRInternet",
    "friendly_name": "姓名",
    "min_value": null,
    "max_value": null,
    "split_str": null
}

enum(枚举)

{
    "name": "",
    "type": "enum",
    "required": true,
    "friendly_value": ["选项1", "选项2", "选项3"],
    "value": ["1", "2", "3"],
    "friendly_name": "下载来源",
    "min_value": null,
    "max_value": null,
    "split_str": null
}

4. 响应配置详解

response对象包含图像提取和其他数据的配置：

"response": {
    "image": {
        "content_type": "",
        "path": "",
        "is_list": false,
        "is_base64": false
    },
    "others": [
        {
            "friendly_name": "",
            "data": [
                {
                    "friendly_name": "",
                    "path": ""
                }
            ]
        }
    ]
}

图像配置image

字段 必需 数据类型 描述
content_type 是 字符串 图像类型 (URL或BINARY)
path 是 字符串 图像在响应中的路径，请注意书写规范
is_list 否 布尔值 是否是图像列表 (缺省值为false)
is_base64 否 布尔值 二进制是否base64编码 (缺省值为false)

常见场景配置示例

  1. 单张URL图片
{
    "content_type": "URL",
    "path": "data.image.url",
    "is_list": false,
    "is_base64": false
}
  1. 多张Base64编码图片
{
    "content_type": "BINARY",
    "path": "images.data",
    "is_list": true,
    "is_base64": true
}

其他数据配置others 

"others": [
    {
        "friendly_name": "图片信息",
        "data": [
            {"friendly_name": "图片宽度", 
             "path": "data.image.info.width"},
            {"friendly_name": "图片高度", 
             "path": "data.image.info.height"}
        ]
    },
    {
        "friendly_name": "用户信息",
        "data": [
            {"friendly_name": "用户ID", 
             "path": "data.user.id"},
            {"friendly_name": "用户名", 
             "path": "data.user.name"}
        ]
    }
]

5. 完整示例

{
    "friendly_name": "API_EXAMPLE", 
    "intro": "示例 API 配置文件", 
    "icon": "https://github.com/user-attachments/assets/83078bfd-fb6a-4ffd-90b2-27bf7f611bf9",
    "link": "https://api.example.com/generate",
    "func": "POST",
    "APICORE_version": "1.0",
    "parameters": [
      {
        "name": "",
        "type": "integer",
        "required": true,
        "value": 5,
        "friendly_name": "生成数量",
        "min_value": 1,
        "max_value": 10,
        "split_str": null
      }, 
      {
        "name": "",
        "type": "boolean",
        "required": true,
        "value": false,
        "friendly_name": "年龄是否大于20",
        "min_value": null,
        "max_value": null,
        "split_str": null
      }, 
      {
        "name": "",
        "type": "list",
        "required": false,
        "value": ["男", "女"],
        "friendly_name": "性别",
        "min_value": null,
        "max_value": null,
        "split_str": "&"
      }, 
      {
        "name": "",
        "type": "string",
        "value": "hello",
        "required": false,
        "friendly_name": "姓名",
        "min_value": null,
        "max_value": null,
        "split_str": null
      }, 
      {
        "name": "",
        "type": "enum",
        "required": true,
        "friendly_value": ["迅雷", "清华镜像", "直接下载"],
        "value": ["xunlei", "tsinghua", "normal"],
        "friendly_name": "下载来源",
        "min_value": null,
        "max_value": null,
        "split_str": null
      }
    ],
    "response": {
      "image": {
        "content_type": "BINARY",
        "path": "data.image.raw",
        "is_list": true,
        "is_base64": false
      },
      "others": [
        {"friendly_name": "图片信息", 
          "data": [
            {"friendly_name": "图片宽度", 
              "path": "data.image.info.width"},
            {"friendly_name": "图片高度", 
              "path": "data.image.info.height"}
            ]
        }, 
        {"friendly_name": "作者信息", 
          "data": [
            {"friendly_name": "作者名称", 
              "path": "data.user.info.name"},
            {"friendly_name": "作者主页", 
              "path": "data.user.info.homepage"}
            ]
        }
      ]
    }
}

验证工具

使用Python验证配置文件：

import json

def validate_config(file_path):
    try:
        with open(file_path, 'r') as f:
            config = json.load(f)
        
        # 基本验证
        assert config.get('APICORE_version') == '1.0', "无效的版本号"
        assert config.get('link') and config.get('func'), "缺少必要的API配置"
        
        # 参数验证
        for param in config.get('parameters', []):
            param_type = param.get('type')
            assert param_type in ['integer', 'boolean', 'list', 'string', 'enum'], "无效的参数类型"
        
        print("配置文件验证通过")
        return True
        
    except (json.JSONDecodeError, AssertionError) as e:
        print(f"配置文件验证失败: {str(e)}")
        return False

# 使用示例
validate_config('api_config.api.json')

Clone this wiki locally