Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

fix(image-generation): stop retrying permanent backend failures

hugohe377e9812c780b
diff --git a/docs/roadmap.md b/docs/roadmap.md
index df632cab..89dbc87a 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -39,7 +39,7 @@ A presentation is four layers: what is on the slide, how it is arranged, how it
| Native WordArt & warped text | Not planned | AI-generated decorative lettering is the preferred visual carrier, with ordinary editable text as the fallback. Native WordArt, text warp, and text-on-path would add a separate authoring and compatibility surface without improving that path, so they are not generated |
| Vector shapes | Systematized | primitive → Office preset → Boolean → freeform construction ladder, with native conversion rules |
| Lines & connectors | Asymmetric by design | Native `p:cxnSp` export is implemented, and endpoint attachment is restored on the preserve/mirror round-trip from a source deck. Newly authored connectors stay unconnected. Binding them would first require deciding which lines are real edges and which are decoration — an intent judgment that no geometric threshold settles, and one that is made by the AI wherever it is placed, so moving it upstream to authoring buys no reliability. The result would be some arrows in a diagram following their node and others not |
-| Icons | Systematized | Bundled libraries with per-project sync; project icons are prepared material |
+| Icons | Systematized | Bundled SVG libraries with per-project sync; project icons are prepared material. Illustrated semantic cues remain generated slices under `images/` for ordinary image composition and never become icon-library entries |
| Logo | Bounded by design | A logo is always existing artwork, never designed here: brand workspaces install officially supplied files as prepared assets — bundled brand presets ship official marks with recorded usage rules — and the simple-icons library covers real company / product marks |
| Images | Systematized | Acquisition, generation, treatment, cropping, layout, composition, embedding, provenance |
| Charts | Systematized | Dedicated authoring reference; SVG by default, native Chart replacement available as an explicit opt-in |
diff --git a/docs/zh/roadmap.md b/docs/zh/roadmap.md
index e6146baf..e26ce9c2 100644
--- a/docs/zh/roadmap.md
+++ b/docs/zh/roadmap.md
@@ -39,7 +39,7 @@
| 原生 WordArt 与文字变形 | 暂不考虑 | 艺术字首选 AI 生成的装饰文字图片,普通可编辑文字负责兜底。原生 WordArt、文字变形与路径文字会额外引入一套创作和兼容性表面,却不能改善这条主路径,因此不生成 |
| 矢量形状 | 系统化 | primitive → Office preset → Boolean → freeform 构造阶梯,附原生转换规范 |
| 线条 / 连接符 | 有意的不对称 | 原生 `p:cxnSp` 导出已实现,端点绑定在来源 deck 的 preserve/mirror 往返路径上会被还原。新创作的连接符保持不连接。要绑定就得先判断哪些线是真实的边、哪些是装饰——这是意图判断,任何几何阈值都定不下来;而无论把这个判断放在导出期还是创作期,做判断的都是 AI,往上游挪并不会更可靠。结果只会是同一张图里有的箭头跟着节点走、有的不走 |
-| 图标 | 系统化 | 内置图标库 + 逐项目同步;项目图标属于已准备材料 |
+| 图标 | 系统化 | 内置 SVG 图标库 + 逐项目同步;项目图标属于已准备材料。插图式语义提示仍是 `images/` 下用于普通图片构图的生成切片,不进入图标库 |
| Logo | 有意边界 | Logo 永远来自既有素材,不在这里设计:brand 工作区把官方提供的文件安装为已准备资产——内置品牌预设附带官方标识及记录在案的使用规则——真实公司 / 产品标识另有 simple-icons 图标库覆盖 |
| 图片 | 系统化 | 获取、生成、处理、裁切、布局、组合、嵌入与来源标注 |
| 图表 | 系统化 | 有专属创作 reference;默认 SVG,原生 Chart 替换为显式 opt-in |
diff --git a/skills/ppt-master/scripts/image_backends/backend_bfl.py b/skills/ppt-master/scripts/image_backends/backend_bfl.py
index ee9fbe09..38305250 100644
--- a/skills/ppt-master/scripts/image_backends/backend_bfl.py
+++ b/skills/ppt-master/scripts/image_backends/backend_bfl.py
@@ -33,6 +33,7 @@ from image_backends.backend_common import (
MAX_RETRIES,
download_image,
http_error,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
poll_json,
@@ -202,6 +203,8 @@ def generate(prompt: str,
)
except Exception as exc:
last_error = exc
+ if is_permanent_error(exc):
+ raise
if attempt >= max_retries:
break
limited = is_rate_limit_error(exc)
diff --git a/skills/ppt-master/scripts/image_backends/backend_common.py b/skills/ppt-master/scripts/image_backends/backend_common.py
index 56355666..ac8c9f91 100644
--- a/skills/ppt-master/scripts/image_backends/backend_common.py
+++ b/skills/ppt-master/scripts/image_backends/backend_common.py
@@ -38,6 +38,60 @@ MAX_RETRIES = 3
RETRY_BASE_DELAY = 10
RETRY_BACKOFF = 2
+_TRANSIENT_CLIENT_STATUSES = {408, 409, 423, 425, 429}
+_HTTP_ERROR_STATUS = re.compile(r"\(([1-5][0-9]{2})\):")
+_PERMANENT_ERROR_TYPES = {
+ "authenticationerror",
+ "badrequesterror",
+ "notfounderror",
+ "permissiondeniederror",
+ "unprocessableentityerror",
+}
+_PERMANENT_ERROR_MARKERS = (
+ "prepayment credits are depleted",
+ "prepaid credits are depleted",
+ "credits are depleted",
+ "insufficient credits",
+ "insufficient balance",
+ "insufficient_quota",
+ "exceeded your current quota",
+ "payment required",
+ "billing is not enabled",
+ "billing not enabled",
+ "billing must be enabled",
+ "billing is disabled",
+ "invalid api key",
+ "api key not valid",
+ "incorrect api key",
+ "authentication failed",
+ "authentication required",
+ "unauthorized",
+ "permission denied",
+ "forbidden",
+ "invalid_argument",
+ "invalid argument",
+ "invalid request",
+ "bad request",
+ "failed_precondition",
+ "failed precondition",
+ "invalid image size",
+ "invalid aspect ratio",
+ "unsupported image size",
+ "unsupported aspect ratio",
+ "unsupported model",
+ "model not found",
+ "model does not exist",
+ "content policy",
+ "request moderated",
+ "content moderated",
+ "prompt was rejected",
+ "blocked by safety",
+)
+
+
+class _RetryableBackendError(RuntimeError):
+ """A backend failure whose enclosing operation should be repeated."""
+
def resolve_output_path(prompt: str, output_dir: str = None,
filename: str = None, ext: str = ".png") -> str:
@@ -276,8 +330,51 @@ def normalize_image_size(image_size: str) -> str:
return s
+def _error_status_code(exc: Exception) -> int | None:
+ """Extract an HTTP-like status code from common SDK exception shapes."""
+ candidates = (
+ getattr(exc, "status_code", None),
+ getattr(exc, "code", None),
+ getattr(getattr(exc, "response", None), "status_code", None),
+ )
+ for value in candidates:
+ if isinstance(value, int) and not isinstance(value, bool):
+ return value
+ if isinstance(value, str) and value.isdigit():
+ return int(value)
+
+ match = _HTTP_ERROR_STATUS.search(str(exc))
+ return int(match.group(1)) if match else None
+
+
+def is_permanent_error(exc: Exception) -> bool:
+ """Return whether retrying the unchanged backend request cannot succeed."""
+ if isinstance(exc, _RetryableBackendError):
+ return False
+ if isinstance(exc, (FileNotFoundError, NotImplementedError, PermissionError)):
+ return True
+
+ status_code = _error_status_code(exc)
+ if (
+ status_code is not None
+ and 400 <= status_code < 500
+ and status_code not in _TRANSIENT_CLIENT_STATUSES
+ ):
+ return True
+
+ error_name = type(exc).__name__.lower()
+ if error_name in _PERMANENT_ERROR_TYPES:
+ return True
+
+ err_str = str(exc).lower()
+ return any(marker in err_str for marker in _PERMANENT_ERROR_MARKERS)
+
+
def is_rate_limit_error(exc: Exception) -> bool:
"""Check whether the exception appears to be rate limiting."""
+ if is_permanent_error(exc):
+ return False
+
err_str = str(exc).lower()
status_code = getattr(exc, "status_code", None)
error_code = getattr(exc, "code", None)
@@ -312,8 +409,11 @@ def retry_delay(attempt: int, rate_limited: bool) -> int:
def download_image(url: str, path: str, headers: dict = None, timeout: int = 180) -> str:
"""Download an image URL and save it to disk."""
- response = requests.get(url, headers=headers or {}, timeout=timeout)
- response.raise_for_status()
+ try:
+ response = requests.get(url, headers=headers or {}, timeout=timeout)
+ response.raise_for_status()
+ except requests.RequestException as exc:
+ raise _RetryableBackendError(f"Image download failed: {exc}") from exc
return save_image_bytes(
response.content,
path,
diff --git a/skills/ppt-master/scripts/image_backends/backend_fal.py b/skills/ppt-master/scripts/image_backends/backend_fal.py
index 7e05bc7a..2a0c0605 100644
--- a/skills/ppt-master/scripts/image_backends/backend_fal.py
+++ b/skills/ppt-master/scripts/image_backends/backend_fal.py
@@ -33,6 +33,7 @@ from image_backends.backend_common import (
MAX_RETRIES,
download_image,
http_error,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
require_api_key,
@@ -164,6 +165,8 @@ def generate(prompt: str,
)
except Exception as exc:
last_error = exc
+ if is_permanent_error(exc):
+ raise
if attempt >= max_retries:
break
limited = is_rate_limit_error(exc)
diff --git a/skills/ppt-master/scripts/image_backends/backend_gemini.py b/skills/ppt-master/scripts/image_backends/backend_gemini.py
index 2511b9c6..bc3076a4 100644
--- a/skills/ppt-master/scripts/image_backends/backend_gemini.py
+++ b/skills/ppt-master/scripts/image_backends/backend_gemini.py
@@ -37,6 +37,7 @@ from google import genai
from google.genai import types
from image_backends.backend_common import (
MAX_RETRIES,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
resolve_output_path,
@@ -262,6 +263,8 @@ def generate(prompt: str,
filename, model, base_url)
except Exception as e:
last_error = e
+ if is_permanent_error(e):
+ raise
if attempt < max_retries and is_rate_limit_error(e):
delay = retry_delay(attempt, rate_limited=True)
print(f"\n [WARN] Rate limit hit (attempt {attempt + 1}/{max_retries + 1}). "
diff --git a/skills/ppt-master/scripts/image_backends/backend_ideogram.py b/skills/ppt-master/scripts/image_backends/backend_ideogram.py
index ab11e67a..45383d8e 100644
--- a/skills/ppt-master/scripts/image_backends/backend_ideogram.py
+++ b/skills/ppt-master/scripts/image_backends/backend_ideogram.py
@@ -33,6 +33,7 @@ from image_backends.backend_common import (
MAX_RETRIES,
download_image,
http_error,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
require_api_key,
@@ -172,6 +173,8 @@ def generate(prompt: str,
)
except Exception as exc:
last_error = exc
+ if is_permanent_error(exc):
+ raise
if attempt >= max_retries:
break
limited = is_rate_limit_error(exc)
diff --git a/skills/ppt-master/scripts/image_backends/backend_minimax.py b/skills/ppt-master/scripts/image_backends/backend_minimax.py
index 6a3fd2f2..d92b1fdd 100644
--- a/skills/ppt-master/scripts/image_backends/backend_minimax.py
+++ b/skills/ppt-master/scripts/image_backends/backend_minimax.py
@@ -34,6 +34,7 @@ from image_backends.backend_common import (
MAX_RETRIES,
detect_image_extension,
http_error,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
require_api_key,
@@ -219,6 +220,8 @@ def generate(prompt: str,
)
except Exception as exc:
last_error = exc
+ if is_permanent_error(exc):
+ raise
if attempt >= max_retries:
break
limited = is_rate_limit_error(exc)
diff --git a/skills/ppt-master/scripts/image_backends/backend_modelscope.py b/skills/ppt-master/scripts/image_backends/backend_modelscope.py
index 434e7905..efdd1167 100644
--- a/skills/ppt-master/scripts/image_backends/backend_modelscope.py
+++ b/skills/ppt-master/scripts/image_backends/backend_modelscope.py
@@ -16,6 +16,7 @@ import requests
from image_backends.backend_common import (
MAX_RETRIES,
http_error,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
require_api_key,
@@ -175,6 +176,8 @@ def generate(prompt: str,
)
except Exception as exc:
last_error = exc
+ if is_permanent_error(exc):
+ raise
if attempt >= max_retries:
break
limited = is_rate_limit_error(exc)
diff --git a/skills/ppt-master/scripts/image_backends/backend_openai.py b/skills/ppt-master/scripts/image_backends/backend_openai.py
index ca624632..6b371779 100644
--- a/skills/ppt-master/scripts/image_backends/backend_openai.py
+++ b/skills/ppt-master/scripts/image_backends/backend_openai.py
@@ -54,6 +54,7 @@ from image_backends.backend_common import (
MAX_RETRIES,
download_image,
http_error,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
resolve_output_path,
@@ -706,6 +707,8 @@ def generate(prompt: str,
filename, model, base_url)
except Exception as e:
last_error = e
+ if is_permanent_error(e):
+ raise
if attempt < max_retries and is_rate_limit_error(e):
delay = retry_delay(attempt, rate_limited=True)
print(f"\n [WARN] Rate limit hit (attempt {attempt + 1}/{max_retries + 1}). "
diff --git a/skills/ppt-master/scripts/image_backends/backend_openrouter.py b/skills/ppt-master/scripts/image_backends/backend_openrouter.py
index 7efc4df3..45a82206 100644
--- a/skills/ppt-master/scripts/image_backends/backend_openrouter.py
+++ b/skills/ppt-master/scripts/image_backends/backend_openrouter.py
@@ -34,6 +34,7 @@ from image_backends.backend_common import (
decode_data_uri,
find_data_uri,
http_error,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
resolve_output_path,
@@ -202,6 +203,8 @@ def generate(prompt: str,
filename, model, base_url)
except Exception as e:
last_error = e
+ if is_permanent_error(e):
+ raise
if attempt < max_retries and is_rate_limit_error(e):
delay = retry_delay(attempt, rate_limited=True)
print(f"\n [WARN] Rate limit hit (attempt {attempt + 1}/{max_retries + 1}). "
diff --git a/skills/ppt-master/scripts/image_backends/backend_qwen.py b/skills/ppt-master/scripts/image_backends/backend_qwen.py
index 06935376..0de8a4ea 100644
--- a/skills/ppt-master/scripts/image_backends/backend_qwen.py
+++ b/skills/ppt-master/scripts/image_backends/backend_qwen.py
@@ -33,6 +33,7 @@ from image_backends.backend_common import (
MAX_RETRIES,
download_image,
http_error,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
require_api_key,
@@ -211,6 +212,8 @@ def generate(prompt: str,
)
except Exception as exc:
last_error = exc
+ if is_permanent_error(exc):
+ raise
if attempt >= max_retries:
break
limited = is_rate_limit_error(exc)
diff --git a/skills/ppt-master/scripts/image_backends/backend_replicate.py b/skills/ppt-master/scripts/image_backends/backend_replicate.py
index 12241619..2b2bc9b3 100644
--- a/skills/ppt-master/scripts/image_backends/backend_replicate.py
+++ b/skills/ppt-master/scripts/image_backends/backend_replicate.py
@@ -33,6 +33,7 @@ from image_backends.backend_common import (
MAX_RETRIES,
download_image,
http_error,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
poll_json,
@@ -191,6 +192,8 @@ def generate(prompt: str,
)
except Exception as exc:
last_error = exc
+ if is_permanent_error(exc):
+ raise
if attempt >= max_retries:
break
limited = is_rate_limit_error(exc)
diff --git a/skills/ppt-master/scripts/image_backends/backend_siliconflow.py b/skills/ppt-master/scripts/image_backends/backend_siliconflow.py
index 77fc56c7..a0daa0a3 100644
--- a/skills/ppt-master/scripts/image_backends/backend_siliconflow.py
+++ b/skills/ppt-master/scripts/image_backends/backend_siliconflow.py
@@ -33,6 +33,7 @@ from image_backends.backend_common import (
MAX_RETRIES,
download_image,
http_error,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
require_api_key,
@@ -169,6 +170,8 @@ def generate(prompt: str,
)
except Exception as exc:
last_error = exc
+ if is_permanent_error(exc):
+ raise
if attempt >= max_retries:
break
limited = is_rate_limit_error(exc)
diff --git a/skills/ppt-master/scripts/image_backends/backend_stability.py b/skills/ppt-master/scripts/image_backends/backend_stability.py
index fd0761b9..aab8aacd 100644
--- a/skills/ppt-master/scripts/image_backends/backend_stability.py
+++ b/skills/ppt-master/scripts/image_backends/backend_stability.py
@@ -32,6 +32,7 @@ import requests
from image_backends.backend_common import (
MAX_RETRIES,
http_error,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
report_resolution,
@@ -163,6 +164,8 @@ def generate(prompt: str,
)
except Exception as exc:
last_error = exc
+ if is_permanent_error(exc):
+ raise
if attempt >= max_retries:
break
limited = is_rate_limit_error(exc)
diff --git a/skills/ppt-master/scripts/image_backends/backend_volcengine.py b/skills/ppt-master/scripts/image_backends/backend_volcengine.py
index 96a5bd99..1cc0d7a1 100644
--- a/skills/ppt-master/scripts/image_backends/backend_volcengine.py
+++ b/skills/ppt-master/scripts/image_backends/backend_volcengine.py
@@ -33,6 +33,7 @@ from image_backends.backend_common import (
MAX_RETRIES,
download_image,
http_error,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
require_api_key,
@@ -190,6 +191,8 @@ def generate(prompt: str,
)
except Exception as exc:
last_error = exc
+ if is_permanent_error(exc):
+ raise
if attempt >= max_retries:
break
limited = is_rate_limit_error(exc)
diff --git a/skills/ppt-master/scripts/image_backends/backend_zhipu.py b/skills/ppt-master/scripts/image_backends/backend_zhipu.py
index 857a24d6..c8e51423 100644
--- a/skills/ppt-master/scripts/image_backends/backend_zhipu.py
+++ b/skills/ppt-master/scripts/image_backends/backend_zhipu.py
@@ -33,6 +33,7 @@ from image_backends.backend_common import (
MAX_RETRIES,
download_image,
http_error,
+ is_permanent_error,
is_rate_limit_error,
normalize_image_size,
require_api_key,
@@ -186,6 +187,8 @@ def generate(prompt: str,
)
except Exception as exc:
last_error = exc
+ if is_permanent_error(exc):
+ raise
if attempt >= max_retries:
break
limited = is_rate_limit_error(exc)
diff --git a/skills/ppt-master/scripts/image_gen.py b/skills/ppt-master/scripts/image_gen.py
index 2ec798c6..d03c8176 100644
--- a/skills/ppt-master/scripts/image_gen.py
+++ b/skills/ppt-master/scripts/image_gen.py
@@ -876,6 +876,8 @@ def _run_manifest(manifest: dict, manifest_path: str, backend_module, *,
and not retried within this run. `Failed` remains retryable and
non-terminal; the Step 5 gate must resolve it by rerunning this
manifest or marking the item `Needs-Manual`.
+ - Permanent auth, billing, model, and request errors skip unchanged
+ backend retries but keep the same repairable `Failed` manifest state.
- Status is written back to the manifest file after each completion;
a Ctrl-C in the middle still preserves done items.
- `Needs-Manual` items are skipped (user processes them externally).
@@ -891,6 +893,7 @@ def _run_manifest(manifest: dict, manifest_path: str, backend_module, *,
output_dir = str(manifest_output_dir)
from image_backends.backend_common import (
+ is_permanent_error,
is_rate_limit_error,
validate_image_file,
)
@@ -983,6 +986,17 @@ def _run_manifest(manifest: dict, manifest_path: str, backend_module, *,
item.pop("last_error", None)
ok_count += 1
print(f" [OK] {item['filename']}")
+ elif isinstance(exc, ValueError) or is_permanent_error(exc):
+ item["status"] = STATUS_FAILED
+ item["last_error"] = (
+ f"Permanent backend error: {exc}"
+ )[:500]
+ fail_count += 1
+ print(
+ f" [FAIL] {item['filename']}: {exc} "
+ "(status=Failed; repair credentials, billing, "
+ "model, or request before retry)"
+ )
elif is_rate_limit_error(exc):
rate_limited = True
attempts = rate_limit_attempts.get(idx, 0) + 1
@@ -1056,8 +1070,9 @@ def _run_manifest(manifest: dict, manifest_path: str, backend_module, *,
if fail_count:
print(
"[Manifest] Failed is retryable and non-terminal. "
- "Resolve failed item(s) by rerunning this manifest or marking them "
- "Needs-Manual before entering Executor."
+ "Repair permanent backend errors before rerunning; retry transient "
+ "failures or follow the owning manual recovery before entering "
+ "Executor."
)
return ok_count, fail_count, skipped