imini-generate

imini 开放平台 API 集成

使用 imini 生成图像 / 视频，或为用户的项目编写集成代码。选择合适的模型、估算成本并处理异步任务。

关于 imini

• 统一端点：https://openapi.imini.ai/imini/router
• 统一认证：一个 Bearer API 密钥即可用于所有模型 — Authorization: Bearer $IMINI_API_KEY
• 统一异步模式：每次生成调用都会返回一个 task_id；轮询任务查询端点，直到 status 为 succeeded 或 failed。可能的值只有 queued / processing / succeeded / failed — 绝不要检查 pending / completed / running。
• 统一错误格式：{ error: { code, message, status, request_id } }
• 模型目录：https://docs.imini.ai/llms.txt — 始终保持最新的模型列表，其中包含定价和各模型的 OpenAPI 规范 URL

步骤 0 — 选择正确的路径

有两条路径。开始前先选择。

用户说……	路径	你要做什么
“生成 / 制作 / 绘制 / 创建一张……的[图像 | 视频]”	A	运行捆绑脚本 — 不生成代码
“用这个提示词试试 imini” / “给我看看……是什么样子”	A	同上
“将 imini 添加到我的项目 / 应用 / 后端”	B	使用用户的语言生成代码模板
“编写一个调用 imini 的 Python/Node/TS 函数”	B	同上
“测试 imini 能否完成 X”	A，然后询问是否还需要代码
用户表达不清楚	询问：“现在一次性生成，还是为你的项目编写集成代码？”

两条路径会共享关于模型的知识（references/model_selection.md），但只有路径 B 需要读取 references/integration_examples.md。路径 A 跳过该文件，是节省 token 的主要方式。

---

路径 A — 一次性生成（捆绑脚本）

此技能附带可执行的 Python 脚本，用于处理提交 + 轮询 + 429/5xx 重试 + 随机抖动 + 结构化错误保留 + 结果下载。你只需调用这些脚本；每次会话都不必用临时 Python 代码重写这套逻辑。

A1 — 预检

运行任何脚本前：

1. 检查 Python：python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3,8) else 1)' — 必须成功。如果失败，告知用户安装 Python 3.8+（macOS：内置；Ubuntu：sudo apt install python3；Windows：winget install Python.Python.3）。
2. 检查 API 密钥：[ -n "$IMINI_API_KEY" ] && echo OK || echo MISSING。如果缺少密钥，指导用户在 shell 中设置（export IMINI_API_KEY='sk-...'）— 不要让他们把密钥粘贴到对话中，否则密钥会出现在 Agent 的记录里。密钥可在 https://imini.ai/api-keys 管理。

A2 — 选择模型（实时获取，绝不硬编码）

如果用户没有指定模型，请运行：

python3 ${SKILL_DIR}/scripts/generate_image.py --list-models    # for images
python3 ${SKILL_DIR}/scripts/generate_video.py --list-models    # for videos

此命令会从 https://docs.imini.ai/llms.txt 获取模型目录（使用 24 小时离线缓存），并打印模型 ID、能力摘要、定价和 OpenAPI 规范 URL。不要在任何地方维护硬编码的模型列表 — imini 发布新模型后，新模型会立即可用。

若要确定哪个模型适合用户提出的需求，请参考 references/model_selection.md。对于复杂场景（例如使用参考视频的 Seedance）的准确价格，请参阅 https://docs.imini.ai/en/guide/pricing。

A3 — 运行脚本

图像（单张，近似 1080p，4K 分辨率）：

python3 ${SKILL_DIR}/scripts/generate_image.py \
    --model google/nano-banana-pro \
    --prompt "a moody cinematic portrait at golden hour" \
    --resolution 4K --aspect-ratio 16:9 \
    --output ./out.png

带有风格 + 素材参考的图像：

python3 ${SKILL_DIR}/scripts/generate_image.py \
    --model google/nano-banana-pro \
    --prompt "place the product in this style" \
    --style-reference ./mood.jpg \
    --reference-image ./product.png \
    --resolution 2K --aspect-ratio 1:1 \
    --output ./out.png

视频（5 秒、1080p，带音频）：

python3 ${SKILL_DIR}/scripts/generate_video.py \
    --model kling/kling-v3 \
    --prompt "drone shot over snowy mountains at sunrise" \
    --duration 5 --resolution 1080P --aspect-ratio 16:9 \
    --audio \
    --output ./drone.mp4

使用首帧 + 尾帧插值的视频：

python3 ${SKILL_DIR}/scripts/generate_video.py \
    --model kling/kling-v3 \
    --prompt "smooth camera move from sunrise to sunset" \
    --start-image ./first.jpg --end-image ./last.jpg \
    --duration 10 --resolution 720P \
    --output ./interp.mp4

长时间运行的视频 — 启动后即可离开：

# Submit only, returns task_id immediately
TASK_ID=$(python3 ${SKILL_DIR}/scripts/generate_video.py \
    --model doubao/seedance-2.0 \
    --prompt "..." --duration 15 --resolution 720P \
    --reference-video ./ref.mp4 \
    --async)
echo "task_id: $TASK_ID"

# Later — resume polling and download
python3 ${SKILL_DIR}/scripts/poll_video_task.py --task-id "$TASK_ID" --output ./out.mp4

A4 — 常见 CLI 模式

所有四个脚本都支持以下标志：

• --print-request — 打印将要发送的 JSON 正文，然后退出。无需 API 密钥。可用于提交前检查是否正确。
• --no-download — 跳过文件下载，改为将结果 URL 打印到标准输出。
• --quiet — 仅输出最终保存路径。
• --verbose — 显示调试级轮询详情。
• --api-key KEY — 覆盖 $IMINI_API_KEY（不建议；密钥会被记录在 Shell 历史中）。
• --timeout SECONDS — 覆盖默认硬超时时间。默认值固定：任意图像为 600s（10 min），任意视频为 1800s（30 min）。权威数值请参阅 references/errors.md。
• --list-models — 从 llms.txt 获取并打印当前模型（缓存 24h）。
• --refresh-cache — 强制实时重新获取 llms.txt。

对于未提供显式标志的字段，请使用以下扩展选项：

• --extra '<json>' — 合并到请求正文的根级别。
• --extra-params '<json>'（仅视频）— 合并到 extra_params（Kling 多镜头、camera_control、negative_prompt 等；happyhorse 的 audio_setting）。

A5 — 向用户报告结果

脚本成功退出后，会打印 saved → <path> (<bytes>, <wxh>)。向用户提供保存路径、使用的模型、时长／分辨率元数据，以及大致的积分成本（来自目录），让用户了解支出情况。

对于多图结果（--num-images > 1），遍历脚本保存的文件路径——不要假设只有 [0]。

---

路径 B — 用户项目的集成代码

当用户希望将 imini 嵌入自己的代码库，而不是在当前工作目录中生成一次性文件时，生成代码模板。

B1 — 获取 API 密钥

确认用户已有 imini API 密钥。引导他们前往 https://imini.ai/api-keys。**切勿将密钥硬编码到生成的代码中。**所有模板都必须从环境变量读取密钥（默认名称为 IMINI_API_KEY）。

B2 — 明确需求

只询问选择模型所需的问题：

1. 图像还是视频？
2. 输入模态：纯文本／参考图像／首尾帧／参考视频／多模态？
3. 质量档位（图像：1K／2K／4K／512；视频：480P／720P／1080P）
4. 时长（仅视频）
5. 要集成的编程语言（Python／Node／TypeScript／cURL）

B3 — 选择模型

像路径 A 那样使用实时目录（scripts/generate_image.py --list-models 或 scripts/fetch_imini_catalog.py），并将 references/model_selection.md 作为能力决策树。提供 1–2 个候选模型，包括模型 ID、能力匹配情况和积分成本。编写代码前，先获得用户明确确认。

B4 — 获取 OpenAPI 规范

针对选定的模型，获取其 Spec: URL 中的 YAML（例如：https://docs.imini.ai/en/openapi/images/nano-banana-pro.yaml）。使用 Agent 提供的任何 HTTP 获取工具，或改用 curl。YAML 格式为简洁的 OpenAPI 3.1.0，且可确定性解析——优先使用它，而非 .md 格式。

B5 — 生成代码

使用 references/integration_examples.md 中的模板。每个生成的代码包都必须包含：

1. 提交函数 — 向生成端点发送 POST 请求，并返回 task_id。
2. 轮询循环 — 使用指数退避和 ±20% 抖动，向任务查询端点发送 GET 请求；429 时退避间隔至少为 5s，并设置硬超时。仅对 succeeded 和 failed 分支处理——绝不使用 completed / running。
3. 结果提取 — 图像任务返回 images[]；视频任务返回 videos[]。每个元素都包含 url，以及 width / height（视频还包含 duration）。始终遍历数组——绝不硬编码 [0]。 某些模型 / 参数会生成多个输出。
4. 保留结构化错误信息 — 失败时显示 error.code、error.message、error.request_id，以便用户记录 request_id 并联系 imini 支持。

支持的模板语言：

• Python（同步，仅使用标准库 — urllib）
• Python（异步，需要 aiohttp ≥ 3.9）
• Node.js（原生 fetch 需要 Node 18+）
• TypeScript（需要 Node 18+）
• cURL（分两步：提交 + 轮询，使用 python3 -c 解析 JSON）

B6 — 生产环境建议

• 通过环境变量提供 API 密钥，绝不硬编码。
• 轮询初始间隔：图像约 2s，视频约 5s。指数退避 ×1.5，最大为 30s，并加入 ±20% 抖动。
• 遇到 HTTP 429 时：下次尝试前将退避间隔下限提高到 ≥5s。
• 超时：权威的场景分类表见 references/errors.md。
• 并发：使用信号量或工作池——不要在并行任务中阻塞于同步轮询。
• 成本控制：记录每次提交的 task_id + 预估积分成本；在上游设置每用户配额。

---

参考文件

• references/workflow.md — 异步任务状态机和轮询策略详情
• references/model_selection.md — 能力决策树（模型选择）
• references/integration_examples.md — 各语言的 Path B 代码模板
• references/errors.md — 权威超时表 + 错误代码 + 重试策略
• scripts/_imini_common.py — 共享的提交 / 轮询 / 上传 / 下载 / 错误处理逻辑（供所有捆绑脚本使用）
• scripts/generate_image.py — Path A：图像生成 CLI
• scripts/generate_video.py — Path A：视频生成 CLI
• scripts/poll_image_task.py — 恢复图像任务 task_id
• scripts/poll_video_task.py — 恢复视频任务 task_id
• scripts/fetch_imini_catalog.py — 原始目录获取器（生成脚本中的 --list-models 封装了相同逻辑）

外部资源

• 平台：https://imini.ai
• 文档：https://docs.imini.ai
• 定价：https://docs.imini.ai/en/guide/pricing
• 更新日志：https://docs.imini.ai/en/changelog
• 支持：[email protected]