agnes-ai-generation

Agnes AI 生成

使用此技能，通过 https://apihub.agnes-ai.com 调用 Agnes 文本、图像和视频生成 API。

快速开始

1. 需要了解端点详情、参数或响应字段时，阅读 references/api.md。
2. 进行实际 API 调用时，使用 scripts/agnes_api.py，不要手动重写 curl 命令。
3. 在 AGNES_API_KEY、AGNES_API_TOKEN 或 APIHUB_AGNES_API_KEY 中提供 API 密钥。切勿打印密钥。
4. 如需进行轻量级实时验证，请运行 smoke-test；默认情况下不会创建视频。图生图测试请添加 --include-image-edit，视频模式测试请明确添加 --video-case <case>。只有在基础文本、文本流式输出、文本工具调用、文生图、图生图、文生视频、图生视频、多图视频、关键帧视频和视频检索均返回成功响应后，才能认为此技能已通过完整测试。

命令

文本生成：

python scripts/agnes_api.py text --prompt "Write a concise product tagline for an AI assistant."

流式文本：

python scripts/agnes_api.py text --prompt "Write a short product intro." --stream

流式输出会进行规范化处理，并包含聚合后的 content、events、done 和简短的 raw_prefix。

图像生成：

python scripts/agnes_api.py image --prompt "A luminous floating city above a misty canyon at sunrise, cinematic realism" --size 1024x768

图生图：

python scripts/agnes_api.py image --prompt "Turn the scene into a rainy cyberpunk night while preserving composition" --image https://example.com/input.png --size 1024x768

文生视频并轮询：

python scripts/agnes_api.py video --prompt "A cinematic shot of a cat walking on the beach at sunset" --poll

图生视频：

python scripts/agnes_api.py video --prompt "Animate subtle camera movement and natural lighting" --image https://example.com/image.png --poll

关键帧 / 多图视频：

python scripts/agnes_api.py video --prompt "Create a smooth cinematic transition between the two keyframes" --image https://example.com/a.png --image https://example.com/b.png --mode keyframes --poll

检索视频任务：

python scripts/agnes_api.py video-get video_123456

轻量级实时冒烟测试：

python scripts/agnes_api.py smoke-test

图像编辑冒烟测试：

python scripts/agnes_api.py smoke-test --include-image-edit

单个视频冒烟测试：

python scripts/agnes_api.py smoke-test --video-case text-to-video

工作流

• 文本聊天 / 补全优先使用 agnes-2.0-flash。
• 不要在自主工具工作流中使用 Agnes Responses API 的多轮函数调用。实时测试显示，提供方可能返回 function_call，但整体 status=completed；使用 previous_response_id 提交 function_call_output 可能会失败。文本生成请使用此技能的聊天补全路径；工具调用仅视为尽力而为的请求格式兼容性测试。
• 文生图、图生图和高信息密度图像生成优先使用 agnes-image-2.1-flash。高密度生成由提示词驱动；请包含主体层级、环境、次要细节、光线、构图和质量要求。
• 文生视频、图生视频、多图视频、关键帧动画、基于提示词的运动与场景控制、电影级输出、异步任务创建、基于轮询的结果检索以及基于种子的可复现生成，优先使用 agnes-video-v2.0。
• 生成图像和视频时，调用图像 / 视频 API 前，请将任何非英语用户提示词转换成流畅的英语生成提示词。英语提示词对 Agnes 视频生成而言更稳定。翻译时请保留具体的视觉细节、风格、光线、构图、运动、摄像机指令和限制条件。
• 对于视频，请记住 API 是异步的：先创建任务；如果创建响应包含 video_id，再进行轮询或通过该 ID 检索。只有在 video_id 缺失时，脚本才会回退到旧版 task_id 查询。
• 脚本会在发送请求前验证图像尺寸、视频帧数、帧率和分辨率。num_frames 必须符合 8n + 1，且 <= 441；81 或 121 是合适的短视频取值。
• 为获得更稳定的生成效果，视频命令默认使用 num_frames=121 和 frame_rate=24。视频冒烟测试默认使用 num_frames=81 和 frame_rate=24。
• 除非用户明确要求测试或生成视频，否则在进行耗时或长时间运行的实时视频生成前，请先提醒用户。
• 请使用 smoke-test --video-case <case> 一次测试一种视频能力，避免同时创建过多任务。支持的用例包括 text-to-video、image-to-video、multi-image 和 keyframes。

当前验证说明

• 已在本地确认：技能元数据验证和 Python 语法。
• 已通过实时 API 确认：基础文本、流式文本、工具调用请求格式、文生图、图生图、高信息密度文生图、中文图像／视频提示词翻译、已完成的文生视频 URL 检索，以及已完成的图生视频 URL 检索。
• 注意：Agnes 可能接受工具调用请求参数，但不一定会返回 tool_calls；需要严格验证工具调用时，请使用 smoke-test --strict-tools。
• 注意：Agnes Responses API 多轮函数调用不适用于 Agent 工具循环；不要依赖它实现 Codex/Claude 风格的自动工具续接。
• 脚本和 smoke-test 选择器支持，但在最近一轮中未重新进行端到端测试：多图视频和关键帧动画。
• 尚未完成端到端确认：所有多图视频和关键帧动画任务的已完成 URL 检索。此前的一项文生视频任务返回了服务提供方的 division by zero 错误，因此请确保视频重试过程可见，并清楚报告服务提供方错误。

输出处理

• 默认直接返回生成的图像／视频 URL。除非用户明确要求本地文件或视觉检查，否则不要下载、保存、打开或检查生成的媒体。
• 对于图像响应，当 extra_body.response_format 为 url 时，预期结果为 URL 格式。
• 对于视频响应，当 status 为 completed 时，从 video_url、url 或 remixed_from_video_id 中提取 URL。
• 对于视频检索，优先使用 GET /agnesapi?video_id=...&model_name=agnes-video-v2.0；旧版 GET /v1/videos/{task_id} 仍可作为备用方案。
• 如果请求失败，请报告 HTTP 状态和服务提供方错误正文，但不要泄露 API 密钥。