| name | external-api |
| description | 外部 API 服务调用技能。安全管理 API 密钥，调用第三方 AI 服务生成资产。 支持 3D 模型、贴图、音频等资产的 AI 生成。
|
| version | 1.0.0 |
| dependencies | ["file-manager"] |
| triggers | [{"pattern":"生成模型|生成贴图|生成音效|AI生成|外部API"}] |
| inputs | [{"name":"service","type":"string","enum":["meshy","tripo3d","stable_diffusion","leonardo","suno","elevenlabs"],"required":true},{"name":"prompt","type":"string","required":true}] |
| outputs | [{"name":"asset_path","type":"string","description":"生成的资产文件路径"}] |
外部 API 服务调用技能
提供第三方 AI 服务的安全调用能力，用于生成游戏资产。
密钥配置
配置步骤
- 复制
.env.template 为 .env.local
- 填入对应服务的 API Key
- 确保
.env.local 已添加到 .gitignore
环境变量模板
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
安全原则
- 永不打印密钥：日志中仅显示密钥是否存在，不显示实际值
- 环境隔离：开发/生产环境使用不同密钥
- 权限最小化：仅申请服务必要的 API 权限
- 错误处理：密钥无效时给出清晰指引，不暴露密钥内容
密钥检查
调用任何外部服务前，先检查密钥配置状态：
interface KeyStatus {
service: string;
configured: boolean;
masked_key?: string;
}
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;
negative_prompt?: string;
topology: string;
target_polycount: number;
}
interface MeshyResponse {
task_id: string;
status: "pending" | "processing" | "completed" | "failed";
model_url?: string;
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"
},
: .(request)
});
response.();
}
Godot 兼容格式：.glb, .gltf
Tripo3D
用途：高质量 3D 模型生成（备选）
API 调用示例：
interface Tripo3DRequest {
prompt: string;
style: string;
}
贴图生成
Stable Diffusion API
用途：2D 贴图、UI 素材、概念图生成
API 调用示例：
interface SDRequest {
prompt: string;
negative_prompt?: string;
width: number;
height: number;
steps: number;
cfg_scale: number;
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,
: request.,
: request.
})
});
data = response.();
.(data.[]., );
}
常用提示词模板：
| 贴图类型 | 提示词模板 |
|---|
| 无缝贴图 | seamless tileable {material} texture, top-down view, 4k, pbr |
| 像素风格 | pixel art {subject}, 16x16 sprite, transparent background |
| UI 图标 | game UI icon of {item}, flat design, transparent background |
| 角色立绘 | {character} character portrait, game art style, detailed |
Leonardo.ai
用途：风格化贴图生成（备选）
音频生成
Suno AI
用途：背景音乐生成
API 调用示例：
interface SunoRequest {
prompt: string;
duration: number;
genre?: string;
mood?: string;
}
interface SunoResponse {
task_id: string;
status: string;
audio_url?: string;
}
常用音乐提示词：
| 场景 | 提示词模板 |
|---|
| 主菜单 | epic orchestral main menu theme, game music, loop-ready |
| 战斗 | intense battle music, fast drums, orchestral, game soundtrack |
| 探索 | ambient exploration music, mysterious, calm, atmospheric |
| Boss战 | boss battle theme, dramatic, intense, choir, orchestral |
ElevenLabs
用途：语音合成（NPC 对话、旁白）
API 调用示例：
interface VoiceRequest {
text: string;
voice_id: string;
model_id: string;
voice_settings: {
stability: number;
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();
await fs.writeFile(localPath, Buffer.from(buffer));
return true;
}
导入到 Godot
下载完成后，通过 MCP 工具通知 Godot 刷新资源：
await callMcpTool("execute_editor_script", {
script: `EditorInterface.get_resource_filesystem().scan()`
});
错误处理
常见错误码
| 错误码 | 含义 | 处理方式 |
|---|
| 401 | API Key 无效 | 提示用户检查 .env.local 配置 |
| 402 | 余额不足 | 提示用户充值或更换服务 |
| 429 | 请求过于频繁 | 等待后重试，增加间隔 |
| 500 | 服务器错误 | 重试或使用备选服务 |
| timeout | 请求超时 | 增加超时时间或重试 |
重试策略
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");
}
费用估算参考
| 服务 | 单次调用成本 | 说明 |
|---|
| Meshy.ai | ~$0.20 | 单个 3D 模型 |
| Stable Diffusion | ~$0.01 | 单张图片 |
| Suno | ~$0.10 | 2分钟音乐 |
| ElevenLabs | ~$0.03 | 1000字符语音 |
建议：
- 开发阶段使用低分辨率/低质量设置测试
- 确认效果后再生成高质量版本
- 批量生成时注意 API 调用限制
