参数对齐指南 - 前端到厂商 API 集成

本文档详细说明如何对齐前端参数定义、API Gateway 验证、Vendor Adapter 转换和数据库配置与 KIE 官方文档，确保参数在整个调用链路中的正确传递。

1️⃣ 前端参数定义 → KIE 文档的"用户输入层"

关键文件

components/integrate-input/components/VideoCreator.tsx (L84-556)
components/integrate-input/components/UniversalGenerationForm.tsx (L120-498)

需要对齐的内容

// 前端表单状态
const formState = {
  aspect_ratio: '16:9',     // KIE 支持哪些值？
  duration: 5,              // KIE 支持 5/10 秒？
  resolution: '720p',       // KIE 支持哪些分辨率？
  camera_fixed: false,      // KIE 是否支持此参数？
  seed: -1,                 // KIE 的随机种子范围？
  enable_safety_checker: true  // KIE 是否有安全检查？
}

对齐检查点

✅ KIE 文档中每个参数的值域范围（如 aspect_ratio 支持 "16:9" | "4:3" | "1:1" 等）
✅ KIE 文档中参数的必填/可选属性
✅ KIE 文档中参数的默认值

2️⃣ API Gateway 参数验证 → KIE 文档的"规则约束"

关键文件

workers/src/api-gateway.js (L681-1104)

特别关注 L447-495: POST /api/initiate-video-generation

需要对齐的内容

// 参数验证规则
const MAX_PROMPT_LENGTH = 2000;  // KIE 的 prompt 最大长度？

// XSS 防护模式
const dangerousPatterns = [...];  // KIE 是否有额外的输入限制？

// 图片验证
const MAX_IMAGE_SIZE = 10 * 1024 * 1024;  // KIE 的图片大小限制？
const magicNumbers = {
  jpeg: [0xFF, 0xD8, 0xFF],
  png: [0x89, 0x50, 0x4E, 0x47],
  webp: [0x52, 0x49, 0x46, 0x46],
};  // KIE 支持哪些图片格式？

对齐检查点

✅ KIE 文档中的输入长度限制
✅ KIE 文档中的文件格式和大小限制
✅ KIE 文档中的特殊字符限制

3️⃣ Vendor Adapter 参数转换 → KIE 文档的"API 格式"

这是参数对齐中最关键的部分，任何转换错误都会导致 API 调用失败。

关键文件（⭐ 最重要）

workers/src/vendors/kie.js (L19-930)

核心函数: transformParameters (L1108-1161)

需要对齐的内容

// 参数映射规则
transformParameters(apiIdentifier, parameters, kieModelName, apiArchitecture) {
  const taskRequest = {
    model: kieModelName,  // KIE 的模型名称格式？
    input: {
      prompt: transformed.prompt,  // 直接传递

      // ⚠️ 关键：aspect_ratio 是否需要转换？
      aspect_ratio: transformed.aspect_ratio,  // "16:9" 还是 "landscape"？

      resolution: transformed.resolution,  // "720p" 还是 1280x720？
      duration: transformed.duration,      // 数字 5 还是字符串 "5"？
      camera_fixed: transformed.camera_fixed,  // 布尔值还是字符串？
      seed: transformed.seed,              // -1 还是 null 表示随机？
      enable_safety_checker: transformed.enable_safety_checker,
    },
    callBackUrl: `https://api.purikura.io/api/callbacks/kie/${jobId}`,
  };
}

对齐检查点（🔥 核心）

✅ KIE API 的请求体结构（JSON Schema）
✅ 每个参数的数据类型（string | number | boolean）
✅ 参数的命名约定（snake_case | camelCase）
✅ 是否需要值转换（如 "16:9" → "landscape"）

已知陷阱（文档中已标注）

// ❌ 错误做法
if (aspect_ratio === '16:9') {
  transformed.aspect_ratio = 'landscape'; // ByteDance 不支持此转换
}

// ✅ 正确做法（ByteDance 模型）
if (transformed.aspect_ratio) {
  taskRequest.input.aspect_ratio = transformed.aspect_ratio; // 保持 "16:9"
}

4️⃣ 数据库模型配置 → KIE 文档的"定价和能力"

关键表

ai_models 表

api_identifier: 'bytedance/v1-lite-text-to-video'
kie_model_name: 'bytedance-v1-lite-text-to-video' (KIE API 的实际模型名)
config_schema: 支持的参数列表
credit_cost_rules: 定价规则

需要对齐的内容

-- 查询当前配置
SELECT name, api_identifier, kie_model_name, config_schema, credit_cost_rules
FROM ai_models
WHERE api_identifier LIKE 'bytedance%' AND is_active = true;

对齐检查点

✅ kie_model_name 是否与 KIE 文档中的模型名称完全一致？
✅ config_schema.parameters 是否包含 KIE 支持的所有参数？
✅ credit_cost_rules 是否与 KIE 的定价文档一致？

示例配置

{
  "config_schema": {
    "parameters": [
      "prompt",
      "aspect_ratio",
      "duration",
      "resolution",
      "camera_fixed",
      "seed",
      "enable_safety_checker"
    ]
  },
  "credit_cost_rules": {
    "per_second_costs": {
      "480p": 2,   // KIE 文档：480p 每秒 2 credits？
      "720p": 4.5, // KIE 文档：720p 每秒 4.5 credits？
      "1080p": 10  // KIE 文档：1080p 每秒 10 credits？
    }
  }
}

📋 实际操作步骤（不跑任务的参数对齐）

Step 1: 获取 KIE 官方文档

# 假设你有 KIE API 文档 URL
curl https://kieai.erweima.ai/api/v1/docs > kie-api-spec.json
# 或手动下载 KIE 提供的模型参数说明

Step 2: 对比前端参数定义

// 1. 打开 components/integrate-input/components/VideoCreator.tsx
// 2. 找到 formState 初始化部分
// 3. 逐一对比 KIE 文档中的参数名、类型、值域

// 示例对比：
KIE 文档: aspect_ratio?: "16:9" | "4:3" | "1:1" | "9:16"
前端代码: aspect_ratio: '16:9' ✅ 匹配

KIE 文档: duration: 5 | 10 (number)
前端代码: duration: 5 ✅ 匹配

KIE 文档: resolution?: "480p" | "720p" | "1080p"
前端代码: resolution: '720p' ✅ 匹配

Step 3: 检查 Vendor Adapter 转换规则

// 1. 打开 workers/src/vendors/kie.js
// 2. 找到 transformParameters 函数（L1108-1161）
// 3. 验证每个参数是否正确映射

// 对比清单：
☐ prompt: 是否直接传递？
☐ aspect_ratio: 是否需要转换（如 "16:9" → "landscape"）？
☐ duration: 是否为数字类型（不是字符串 "5"）？
☐ resolution: 是否保持 "720p" 格式（不是 1280x720）？
☐ seed: -1 是否表示随机（还是 null？还是不传？）？

Step 4: 验证数据库配置

-- 1. 查询当前 ByteDance 模型配置
SELECT
  api_identifier,
  kie_model_name,
  config_schema->'parameters' as supported_params,
  credit_cost_rules
FROM ai_models
WHERE api_identifier = 'bytedance/v1-lite-text-to-video';

-- 2. 对比 KIE 文档：
-- ☐ kie_model_name 是否正确？（如 "bytedance-v1-lite-text-to-video"）
-- ☐ supported_params 是否包含所有 KIE 支持的参数？
-- ☐ credit_cost_rules 定价是否准确？

Step 5: 创建参数对齐检查表

KIE 参数对齐检查表 (bytedance/v1-lite-text-to-video)

参数名	KIE 文档值域	前端默认值	Adapter 转换规则	数据库配置	状态
`prompt`	string (max 2000)	✅	✅ 直接传递	✅	✅
`aspect_ratio`	"16:9"\|"4:3"\|"1:1"\|"9:16"	✅ "16:9"	⚠️ 需确认不转换	✅	⚠️
`duration`	5 \| 10	✅ 5	✅ 数字类型	✅	✅
`resolution`	"480p"\|"720p"\|"1080p"	✅ "720p"	✅ 保持字符串	✅	✅
`camera_fixed`	boolean	✅ false	✅ 布尔值	✅	✅
`seed`	number \| -1 (随机)	✅ -1	⚠️ 需确认 -1 还是 null	✅	⚠️
`enable_safety_checker`	boolean	✅ true	✅ 布尔值	✅	✅

🔍 快速验证方法（不实际调用 API）

方法 1: 单元测试模拟

// tests/parameter-alignment.test.js
import { KieAiAdapter } from '../workers/src/vendors/kie.js';

describe('KIE Parameter Alignment', () => {
  it('should transform ByteDance parameters correctly', () => {
    const adapter = new KieAiAdapter({}, {});

    const input = {
      prompt: 'test',
      aspect_ratio: '16:9',
      duration: 5,
      resolution: '720p',
      camera_fixed: false,
      seed: -1,
    };

    const result = adapter.transformParameters(
      'bytedance/v1-lite-text-to-video',
      input,
      'bytedance-v1-lite-text-to-video',
      'task_system'
    );

    // 验证转换结果
    expect(result.model).toBe('bytedance-v1-lite-text-to-video');
    expect(result.input.aspect_ratio).toBe('16:9'); // 不转换
    expect(result.input.duration).toBe(5); // 数字类型
    expect(typeof result.input.seed).toBe('number');
  });
});

方法 2: 日志输出对比

// workers/src/vendors/kie.js (L1108)
transformParameters(apiIdentifier, parameters, kieModelName, apiArchitecture) {
  // ... 转换逻辑 ...

  // 添加日志输出
  console.log('=== Parameter Transformation ===');
  console.log('Input:', JSON.stringify(parameters, null, 2));
  console.log('Output:', JSON.stringify(taskRequest, null, 2));
  console.log('KIE Model Name:', kieModelName);

  return taskRequest;
}

方法 3: 对比 KIE 示例请求

# KIE 文档提供的示例请求（假设）
curl -X POST 'https://kieai.erweima.ai/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer xxx' \
  -d '{
    "model": "bytedance-v1-lite-text-to-video",
    "input": {
      "prompt": "a cat",
      "aspect_ratio": "16:9",
      "duration": 5,
      "resolution": "720p"
    }
  }'

你的 Adapter 生成的请求（通过日志输出）:

{
  "model": "bytedance-v1-lite-text-to-video",
  "input": {
    "prompt": "a cat",
    "aspect_ratio": "16:9",  // ✅ 格式一致
    "duration": 5,           // ✅ 类型一致
    "resolution": "720p"     // ✅ 值一致
  },
  "callBackUrl": "https://api.purikura.io/api/callbacks/kie/xxx"
}

⚠️ 常见参数对齐陷阱（基于验证报告）

陷阱 1: aspect_ratio 格式转换

将 "16:9" 转换为 "landscape" — 某些 AI 厂商使用这种格式，但 ByteDance 不支持

// ❌ 错误：将 "16:9" 转换为 "landscape"
if (aspect_ratio === '16:9') {
  transformed.aspect_ratio = 'landscape';
}

// ✅ 正确：保持 "16:9" 原始格式
taskRequest.input.aspect_ratio = transformed.aspect_ratio;

陷阱 2: seed 随机值表示

// KIE 文档可能要求：
// - 方案 A: seed = -1 表示随机
// - 方案 B: seed = null 表示随机
// - 方案 C: 不传 seed 字段表示随机

// 需要明确 KIE 的约定
if (transformed.seed !== undefined && transformed.seed !== -1) {
  taskRequest.input.seed = transformed.seed;
}

// 或
taskRequest.input.seed = transformed.seed === -1 ? null : transformed.seed;

陷阱 3: duration 类型

// ❌ 错误：字符串 "5"
taskRequest.input.duration = "5";

// ✅ 正确：数字 5
taskRequest.input.duration = 5;

📝 总结：参数对齐的 4 个关键文件

#	文件路径	作用	对齐重点
1	`components/integrate-input/components/VideoCreator.tsx`	前端参数定义	值域范围、默认值
2	`workers/src/api-gateway.js` (L447-495)	参数验证	输入限制、格式检查
3	`workers/src/vendors/kie.js` (L1108-1161)	参数转换（核心）	映射规则、类型转换
4	数据库 `ai_models` 表	模型配置	模型名、支持参数、定价

建议的对齐流程

获取 KIE 官方文档
逐一对比上述 4 个文件
创建参数对齐检查表
通过日志输出验证转换结果
（可选）编写单元测试确保对齐正确

实用工具脚本

参数对齐验证脚本

// scripts/verify-parameter-alignment.js

const fs = require('fs');
const path = require('path');

// 读取前端参数定义
function getFrontendParams() {
  const file = fs.readFileSync(
    path.join(__dirname, '../components/integrate-input/components/VideoCreator.tsx'),
    'utf-8'
  );

  // 提取 formState 定义
  const match = file.match(/formState\s*=\s*{([^}]+)}/s);
  if (match) {
    console.log('Frontend Parameters:', match[1]);
  }
}

// 读取 Adapter 转换逻辑
function getAdapterTransformation() {
  const file = fs.readFileSync(
    path.join(__dirname, '../workers/src/vendors/kie.js'),
    'utf-8'
  );

  // 提取 transformParameters 函数
  const match = file.match(/transformParameters\([^)]+\)\s*{([\s\S]+?)^  }/m);
  if (match) {
    console.log('Adapter Transformation:', match[1].substring(0, 500));
  }
}

// 执行验证
getFrontendParams();
getAdapterTransformation();

运行脚本：

node scripts/verify-parameter-alignment.js

下一步行动

立即验证

获取最新的 KIE API 文档
创建参数对齐检查表
验证所有参数的类型和值域
检查数据库配置的完整性

持续监控

添加参数验证单元测试
设置 CI/CD 参数对齐检查
监控 API 调用失败率
定期更新参数对齐文档

文档版本: v1.0 创建日期: 2025-11-07 维护者: AI Engineering Team 下次审查: 每次 KIE API 更新时