External API

外部 API 服务调用技能

提供第三方 AI 服务的安全调用能力，用于生成游戏资产。

密钥配置

配置步骤

1. 复制 .env.template 为 .env.local
2. 填入对应服务的 API Key
3. 确保 .env.local 已添加到 .gitignore

环境变量模板

# ===== 3D 模型生成服务 =====
MESHY_API_KEY=your_meshy_api_key_here
TRIPO3D_API_KEY=your_tripo3d_api_key_here

# ===== 贴图生成服务 =====
SD_API_KEY=your_stable_diffusion_api_key_here
SD_API_ENDPOINT=https://api.stability.ai
LEONARDO_API_KEY=your_leonardo_api_key_here

# ===== 音频生成服务 =====
SUNO_API_KEY=your_suno_api_key_here
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here

# ===== 通用配置 =====
API_TIMEOUT=60
API_RETRY_COUNT=3

安全原则

1. 永不打印密钥：日志中仅显示密钥是否存在，不显示实际值
2. 环境隔离：开发/生产环境使用不同密钥
3. 权限最小化：仅申请服务必要的 API 权限
4. 错误处理：密钥无效时给出清晰指引，不暴露密钥内容

密钥检查

调用任何外部服务前，先检查密钥配置状态：

interface KeyStatus {
  service: string;
  configured: boolean;
  masked_key?: string;  // 如 "sk-****abcd"
}

function checkApiKeys(): KeyStatus[] {
  return [
    { service: "MESHY", configured: !!process.env.MESHY_API_KEY },
    { service: "STABLE_DIFFUSION", configured: !!process.env.SD_API_KEY },
    { service: "SUNO", configured: !!process.env.SUNO_API_KEY },
    // ...
  ];
}

可用服务

3D 模型生成

Meshy.ai

用途：文本到 3D 模型生成

API 调用示例：

interface MeshyRequest {
  prompt: string;           // 模型描述
  art_style: string;        // "realistic" | "cartoon" | "low-poly" | "sculpture"
  negative_prompt?: string; // 排除元素
  topology: string;         // "quad" | "triangle"
  target_polycount: number; // 目标面数
}

interface MeshyResponse {
  task_id: string;
  status: "pending" | "processing" | "completed" | "failed";
  model_url?: string;       // glTF/GLB 下载地址
  thumbnail_url?: string;
}

async function generateModel(request: MeshyRequest): Promise<MeshyResponse> {
  const response = await fetch("https://api.meshy.ai/v1/text-to-3d", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.MESHY_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(request)
  });
  return response.json();
}

Godot 兼容格式：.glb, .gltf

Tripo3D

用途：高质量 3D 模型生成（备选）

API 调用示例：

interface Tripo3DRequest {
  prompt: string;
  style: string;  // "game-ready" | "high-poly" | "stylized"
}

贴图生成

Stable Diffusion API

用途：2D 贴图、UI 素材、概念图生成

API 调用示例：

interface SDRequest {
  prompt: string;
  negative_prompt?: string;
  width: number;      // 512, 768, 1024
  height: number;
  steps: number;      // 20-50
  cfg_scale: number;  // 7-12
  seed?: number;
}

async function generateTexture(request: SDRequest): Promise<Buffer> {
  const response = await fetch(`${process.env.SD_API_ENDPOINT}/v1/generation/stable-diffusion-xl-1024-v1-0/text-to-image`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SD_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      text_prompts: [{ text: request.prompt, weight: 1 }],
      cfg_scale: request.cfg_scale,
      width: request.width,
      height: request.height,
      steps: request.steps
    })
  });
  const data = await response.json();
  return Buffer.from(data.artifacts[0].base64, "base64");
}

常用提示词模板：

Leonardo.ai

用途：风格化贴图生成（备选）

音频生成

Suno AI

用途：背景音乐生成

API 调用示例：

interface SunoRequest {
  prompt: string;         // 音乐描述
  duration: number;       // 秒数 (最大 120)
  genre?: string;         // "orchestral" | "electronic" | "ambient" ...
  mood?: string;          // "epic" | "peaceful" | "tense" ...
}

interface SunoResponse {
  task_id: string;
  status: string;
  audio_url?: string;     // MP3/WAV 下载地址
}

常用音乐提示词：

ElevenLabs

用途：语音合成（NPC 对话、旁白）

API 调用示例：

interface VoiceRequest {
  text: string;
  voice_id: string;
  model_id: string;       // "eleven_multilingual_v2"
  voice_settings: {
    stability: number;    // 0-1
    similarity_boost: number;
  };
}

async function generateVoice(request: VoiceRequest): Promise<Buffer> {
  const response = await fetch(`https://api.elevenlabs.io/v1/text-to-speech/${request.voice_id}`, {
    method: "POST",
    headers: {
      "xi-api-key": process.env.ELEVENLABS_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(request)
  });
  return Buffer.from(await response.arrayBuffer());
}

资产下载与导入流程

下载资产

async function downloadAsset(url: string, localPath: string): Promise<boolean> {
  const response = await fetch(url);
  const buffer = await response.arrayBuffer();
  
  // 写入到项目 assets 目录
  await fs.writeFile(localPath, Buffer.from(buffer));
  
  return true;
}

导入到 Godot

下载完成后，通过 MCP 工具通知 Godot 刷新资源：

// 刷新文件系统
await callMcpTool("execute_editor_script", {
  script: `EditorInterface.get_resource_filesystem().scan()`
});

错误处理

常见错误码

重试策略

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries: number = 3,
  delay: number = 1000
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(r => setTimeout(r, delay * (i + 1)));
    }
  }
  throw new Error("Max retries exceeded");
}

费用估算参考

建议：

• 开发阶段使用低分辨率/低质量设置测试
• 确认效果后再生成高质量版本
• 批量生成时注意 API 调用限制