Back to Details

ugen

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
ugen
작업을 수행할 때 아래 순서를 그대로 따른다.
执行
ugen
操作时，请严格遵循以下步骤。

목표

目标

  • 실행 가능한 생성 명령을 빠르게 만든다.
  • 입력 순서를 보존한 멀티 파트 프롬프트를 구성한다.
  • 실패 시 원인을 분리하고 즉시 재시도 가능한 수정안을 만든다.
  • 快速创建可执行的生成命令。
  • 构建保留输入顺序的多部分提示词。
  • 失败时定位原因并制定可立即重试的修正方案。

표준 절차

标准流程

  1. 모델과 모달리티를 확인한다.
  2. 토큰 제공 방식을 확정한다.
  3. 최소 입력으로 1회 성공시킨다.
  4. 옵션을 추가하며 품질을 튜닝한다.
  5. 실패 케이스를 점검하고 재현 가능한 해결 명령을 남긴다.
  1. 确认模型与模态。
  2. 确定令牌提供方式。
  3. 用最小输入完成一次成功生成。
  4. 添加参数调优生成质量。
  5. 检查失败案例并留存可复现的解决命令。

1) 모델 확인

1) 模型确认

먼저 모델 범위를 고정한다.
bash
ugen models
ugen models --provider gemini --modality image
ugen models --provider openai --modality video
모델 ID는 출력된 값을 그대로 사용한다.
首先固定模型范围。
bash
ugen models
ugen models --provider gemini --modality image
ugen models --provider openai --modality video
模型ID直接使用输出值。

2) 인증 처리

2) 认证处理

환경변수가 있으면 자동 사용한다. 없으면 
password
프롬프트로 입력한다.
  • Gemini: 
    GEMINI_API_KEY
    또는 
    GOOGLE_API_KEY
  • OpenAI: 
    OPENAI_API_KEY
  • Grok(xAI): 
    XAI_API_KEY
예시:
bash
export OPENAI_API_KEY="***"
ugen models --provider openai
若存在环境变量则自动使用，否则通过
password
提示输入。
  • Gemini: 
    GEMINI_API_KEY
    或 
    GOOGLE_API_KEY
  • OpenAI: 
    OPENAI_API_KEY
  • Grok(xAI): 
    XAI_API_KEY
示例:
bash
export OPENAI_API_KEY="***"
ugen models --provider openai

3) 입력 구성 규칙

3) 输入构法规

--part
는 반복 가능하며 순서가 그대로 전달된다.
  • text:...
  • image:/path/to/file.png
규칙:
  • 텍스트 지시는 짧은 단위로 분해한다.
  • 이미지 경로는 실행 전에 존재 여부를 확인한다.
  • 여러 입력이 필요한 경우 
    text/image
    를 의도한 순서대로 배치한다.
예시:
bash
--part text:"구도 유지" image:./ref1.png --part text:"색감만 반영" image:./ref2.jpg
--part
参数可重复使用，且顺序会被原样传递。
  • text:...
  • image:/path/to/file.png
规则:
  • 文本指令拆分为简短单元。
  • 执行前确认图片路径是否存在。
  • 若需多个输入，按预期顺序排列
    text/image
    。
示例:
bash
--part text:"构图保持" image:./ref1.png --part text:"仅反映色调" image:./ref2.jpg

4) 이미지 생성 기본 템플릿

4) 图片生成基础模板

텍스트 기반:
bash
ugen generate image \
  --provider openai \
  --model gpt-image-1.5 \
  --part text:"눈 오는 밤 네온 거리의 고양이" \
  --option size=1024x1024 quality=high
텍스트+이미지 기반:
bash
ugen generate image \
  --provider gemini \
  --model gemini-2.5-flash-image-preview \
  --part text:"구도를 유지" image:./ref.png text:"색감을 따뜻하게"
基于文本:
bash
ugen generate image \
  --provider openai \
  --model gpt-image-1.5 \
  --part text:"下雪夜晚霓虹街道的猫" \
  --option size=1024x1024 quality=high
基于文本+图片:
bash
ugen generate image \
  --provider gemini \
  --model gemini-2.5-flash-image-preview \
  --part text:"保持构图" image:./ref.png text:"调整为暖色调"

5) 비디오 생성 기본 템플릿

5) 视频生成基础模板

bash
ugen generate video \
  --provider openai \
  --model sora-2 \
  --part text:"비 오는 도시를 달리는 고양이" image:./first-frame.png \
  --option seconds=8 size=1280x720
긴 작업은 타임아웃/폴링을 조정한다.
bash
ugen generate video ... --timeout-ms 1800000 --poll-interval-ms 7000
bash
ugen generate video \
  --provider openai \
  --model sora-2 \
  --part text:"雨中城市奔跑的猫" image:./first-frame.png \
  --option seconds=8 size=1280x720
长任务需调整超时/轮询设置。
bash
ugen generate video ... --timeout-ms 1800000 --poll-interval-ms 7000

6) 옵션 전달 규칙

6) 参数传递规则

단순 키-값은 
--option
, 복잡한 구조는 
--options-json
을 사용한다.
bash
ugen generate video \
  --provider gemini \
  --model veo-3.1-generate-preview \
  --part text:"해변 일출 타임랩스" \
  --option durationSeconds=8 aspectRatio=16:9 \
  --options-json '{"numberOfVideos":1,"generateAudio":false}'
해석 규칙:
  • true/false/null
    자동 타입 변환
  • 숫자 문자열 자동 숫자 변환
  • --options-json
    값이 최종 병합값으로 적용
简单键值对使用
--option
，复杂结构使用
--options-json
。
bash
ugen generate video \
  --provider gemini \
  --model veo-3.1-generate-preview \
  --part text:"海滩日出延时摄影" \
  --option durationSeconds=8 aspectRatio=16:9 \
  --options-json '{"numberOfVideos":1,"generateAudio":false}'
解析规则:
  • 自动转换
    true/false/null
    类型
  • 自动将数字字符串转换为数字
  • --options-json
    的值会作为最终合并值生效

7) 트러블슈팅

7) 故障排查

지원하지 않는 provider

不支持的供应商

  • gemini|openai|grok
    중 하나로 수정한다.
  • 修改为
    gemini|openai|grok
    中的一个。

이미지 파일을 찾을 수 없습니다

无法找到图片文件

  • 파일 경로 오타를 수정한다.
  • 상대경로 대신 절대경로로 재시도한다.
  • 修正文件路径拼写错误。
  • 替换相对路径为绝对路径后重试。

인증 실패 (
401
, 
permission denied
)

认证失败 (
401
, 
permission denied
)

  • provider와 토큰 종류를 다시 맞춘다.
  • 오래된 환경변수를 제거하고 다시 입력한다.
  • 重新匹配供应商与令牌类型。
  • 删除旧的环境变量后重新输入。

비디오 생성 지연/타임아웃

视频生成延迟/超时

  • --timeout-ms
    를 늘린다.
  • seconds
    , 
    size
    , 
    resolution
    을 낮춘다.
  • 增大
    --timeout-ms
    参数值。
  • 降低
    seconds
    、
    size
    、
    resolution
    参数值。

모델이 입력 타입 거부

模型拒绝输入类型

  • ugen models --provider ... --modality ...
    로 지원 입력을 재확인한다.
  • text-only 모델에는 이미지 파트를 제거한다.
  • 通过
    ugen models --provider ... --modality ...
    重新确认支持的输入类型。
  • 移除纯文本模型中的图片部分。

8) 결과 확인 체크리스트

8) 结果确认清单

  • 명령이 
    완료: provider/modality/model
    을 출력하는지 확인한다.
  • 출력 파일 경로가 
    outputs/
    아래 생성됐는지 확인한다.
  • 실패 시 오류 메시지와 함께 재실행 가능한 명령을 남긴다.
  • 确认命令输出
    完成: provider/modality/model
    。
  • 确认输出文件路径在
    outputs/
    目录下生成。
  • 失败时留存包含错误信息的可重执行命令。

9) 빠른 치트시트

9) 快速参考手册

bash
ugen models
ugen generate image --provider openai --model gpt-image-1.5 --part text:"..."
ugen generate video --provider openai --model sora-2 --part text:"..." image:./first.png
ugen generate image --provider gemini --model imagen-4.0-generate-001 --part text:"..." --options-json '{"numberOfImages":2}'
bash
ugen models
ugen generate image --provider openai --model gpt-image-1.5 --part text:"..."
ugen generate video --provider openai --model sora-2 --part text:"..." image:./first.png
ugen generate image --provider gemini --model imagen-4.0-generate-001 --part text:"..." --options-json '{"numberOfImages":2}'