cj-grok-media-studio

name	cj-grok-media-studio
description	Use when the user wants one Grok workflow for text/image/video generation and image editing with automatic defaults.

CJ Grok Media Studio

统一封装 grok2api 的 4 种媒体模式，自动补默认参数并把结果下载到本地：

• 图片输出目录：output/images
• 视频输出目录：output/videos
• CLI 最终输出：保存文件的绝对路径

触发条件

• 用户要做文生图、图生图、文生视频、图生视频
• 用户希望统一走一个 CLI 并使用默认参数
• 用户希望 API 结果自动下载为本地文件

CLI

python scripts/grok_media.py --mode <mode> --prompt "<text>" [--image <path-or-url>]

可选参数（不传则使用默认值）：

• --size（默认 1024x1024）
• --n（默认 1）
• --response-format（默认 url）
• --aspect-ratio（默认 3:2）
• --video-length（默认 6）
• --resolution-name（默认 480p）
• --preset（默认 normal）

4 种模式与默认参数

1. text_to_image

• endpoint: POST /v1/images/generations
• 默认：model=grok-imagine-1.0,size=1024x1024,n=1,response_format=url

2. image_to_image

• endpoint: POST /v1/images/edits（multipart/form-data）
• 默认：model=grok-imagine-1.0-edit,size=1024x1024,n=1,response_format=url
• --image 支持本地路径/URL；URL 会先下载临时文件，再按文件上传

3. text_to_video

• endpoint: POST /v1/chat/completions（model=grok-imagine-1.0-video）
• 默认：aspect_ratio=3:2,video_length=6,resolution_name=480p,preset=normal

4. image_to_video

• endpoint: POST /v1/chat/completions（model=grok-imagine-1.0-video）
• 本地 --image 会转换为 data URI 后放入 messages[].content[].image_url.url
• URL 图片则原样作为 image_url.url

环境变量

只使用以下两个变量：

• GROK2API_BASE_URL
• GROK2API_API_KEY

运行示例（每种模式一条）

python scripts/grok_media.py --mode text_to_image --prompt "a cat on mars"
python scripts/grok_media.py --mode image_to_image --prompt "make it watercolor" --image "./input.png"
python scripts/grok_media.py --mode text_to_video --prompt "slow ocean waves at sunset"
python scripts/grok_media.py --mode image_to_video --prompt "camera pushes in gently" --image "./frame.png"

跨平台说明

• 路径统一由 pathlib 处理，支持 Linux/macOS/Windows。
• 输出目录会自动创建；文件名基于时间戳自动生成。
• URL 下载与 API 调用都使用 requests，无需平台专属命令。

故障排查

现象	常见原因	处理方式
GROK2API_BASE_URL and GROK2API_API_KEY are required	.env 未配置或变量名不匹配	检查 assets/.env.example 并在 .env 写入两个变量
--image is required for image_to_image/image_to_video	模式需要图片但未传 --image	增加 --image 参数
Unsupported image type	本地图扩展名不在支持列表（png/jpg/jpeg/webp）	转换为支持格式后重试
下载失败	上游返回 URL 无效或网络问题	重试；确认上游返回可访问直链
API 4xx/5xx	key/base_url 错误或上游故障	检查 key、base_url、请求参数与 API 状态

验证清单

• .env 已设置 GROK2API_BASE_URL 与 GROK2API_API_KEY
• python -m pytest -q 通过
• 四种模式命令都可执行（成功下载文件或返回可操作的上游错误）