sketch-ai-provider-debug

joelklabo 的头像作者 joelklabo

Debug OpenAI/Gemini image generation failures for Sketch Magic. Use when `/api/convert` returns 500, when models are unsupported, when outputs are empty, or when provider timeouts/quota errors appear.

📖 中文导读:Debug OpenAI/Gemini image generation failures for Sketch Magic. Use when `/api/convert` returns 500, when models are unsupported, when outputs are empty, or when provider timeouts/quota errors appear. 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: sketch-ai-provider-debug description: Debug OpenAI/Gemini image generation failures for Sketch Magic. Use when /api/convert returns 500, when models are unsupported, when outputs are empty, or when provider timeouts/quota errors appear.

Sketch AI Provider Debug

Overview

Provide a consistent debug flow for image generation failures across OpenAI and Gemini providers without leaking secrets.

Workflow

1) Verify configuration

  • Confirm OPENAI_API_KEY / GEMINI_API_KEY exist.
  • Confirm DEFAULT_PROVIDER, OPENAI_IMAGE_MODEL, GEMINI_IMAGE_MODEL match supported models.
  • Use /api/health to confirm defaults.

2) Reproduce with a controlled request

  • Use a tiny PNG and short prompt.
  • Use curl to hit /api/convert (multipart form data).
  • Keep logs visible (server + client).

3) Interpret common failures

  • 500: provider error, missing key, quota, or model mismatch.
  • 400: invalid image type, size, or prompt.
  • Timeout: provider latency or host timeout config.

4) Fix or adjust

  • Swap to a known-good model.
  • Reduce image size or prompt complexity.
  • Confirm provider SDK versions align with supported endpoints.

5) Report safely

  • Do not log API keys or raw image bytes.
  • Summarize error codes and timing only.

References

  • references/openai-image-api.md
  • references/gemini-image-api.md