.env.example

# 复制为 .env 后编辑，勿提交 .env。以 # 开头的配置需取消注释才会生效。
# 可选参数不用时保持注释；默认值在变量未设置时生效，不要填写空值。
# 修改后重启后端；终端中已导出的同名环境变量优先。

# ── OpenAI 兼容对话接口（使用创作助手时，以下三项必填）──
# 接口和模型需支持流式输出与工具调用；模型名称填写服务商提供的标识。
OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=your_base_url
OPENAI_MODEL=your_model_name
# BASE_URL 填写服务商的完整 API 基础地址，例如 https://your-gateway/v1。

# ── OpenAI 兼容生图（与对话 LLM 独立配置）──
# 不使用生图时，整个 IMAGE_* 部分可以保持注释。
# 生图密钥不会自动复用 OPENAI_API_KEY，即使相同也需单独填写。
# IMAGE_API_KEY=your_image_api_key
# 明确填写生图服务的 API 基础地址，不要拼接 /images/generations。
# 未设置时 SDK 会读取 OPENAI_BASE_URL，再回退到 https://api.openai.com/v1。
# IMAGE_BASE_URL=https://your-image-gateway/v1
# 以下是代码默认值；模型名称与尺寸需要服务商支持。
# IMAGE_MODEL=gpt-image-2
# IMAGE_SIZE=1024x1024
# 卡片生图按钮与助手生图工具共用此配置，服务需返回 Base64 PNG 图片。

# 角色/地点的 MODEL 和 SIZE 分别覆盖通用配置；未设置时回退到 IMAGE_MODEL/IMAGE_SIZE。
# 两类图片共用 IMAGE_API_KEY 和 IMAGE_BASE_URL，不是分别配置两个服务。
# 角色立绘示例：透明竖图，需服务商支持对应模型、尺寸和透明背景。
# 当前实现拒绝 gpt-image-2* 与 transparent 组合；透明角色可改用支持它的模型。
# IMAGE_CHARACTER_MODEL=gpt-image-1
# IMAGE_CHARACTER_SIZE=1024x1536
# IMAGE_CHARACTER_BACKGROUND=transparent
# 地点背景示例：不透明横图。
# IMAGE_LOCATION_MODEL=gpt-image-2
# IMAGE_LOCATION_SIZE=1536x1024
# IMAGE_LOCATION_BACKGROUND=opaque
# BACKGROUND 可选 transparent / opaque / auto；未设置则不发送此参数，由模型决定。
# 模型不支持背景参数时，保持对应行注释。角色默认也不会自动启用透明背景。
# 生图超时（秒）与临时接口错误重试次数；0 次表示不重试。
# IMAGE_TIMEOUT=180
# IMAGE_MAX_RETRIES=2

# ── 可选项 ──
# LLM_MAX_TOKENS=8192   # 最大输出 token（生成长度）；输入/总长由模型上下文窗口决定
# LLM_TIMEOUT=180      # 对话请求超时（秒），不是整个 Agent 任务的总时限
# LLM_MAX_RETRIES=2     # 瞬时错误（连接失败/5xx/限流）自动重试次数
# 工作区目录（用户项目数据），默认 <repo>/workspace
# NARRATIVE_FORGE_WORKSPACE=/abs/path/to/workspace