---
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`