@unlimiting/unlimitgen 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: '릴리즈 태그 (예: v0.2.0)'
+        required: false
+        type: string
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: npm
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Verify package name
+        run: |
+          PKG_NAME=$(node -p "require('./package.json').name")
+          echo "package: $PKG_NAME"
+          test "$PKG_NAME" = "@unlimiting/unlimitgen"
+
+      - name: Publish (Trusted Publishing + Provenance)
+        run: npm publish --access public --provenance

package/README.md

@@ -0,0 +1,129 @@
+**ugen**
+
+Gemini / OpenAI / Grok(xAI) 모델로 이미지/동영상을 생성하는 CLI입니다.
+
+- 이미지
+  - Gemini: `gemini-3-pro-image-preview`, `gemini-2.5-flash-image-preview`, `imagen-4.0-generate-001`, `imagen-4.0-ultra-generate-001`, `imagen-4.0-fast-generate-001`
+  - OpenAI: `gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`
+  - Grok: `grok-imagine-image`, `grok-imagine-image-pro`
+- 동영상
+  - Gemini: `veo-3.1-generate-preview`, `veo-3.1-fast-generate-preview`
+  - OpenAI: `sora-2`, `sora-2-pro`
+  - Grok: `grok-imagine-video`
+
+> 참고: xAI(Grok)는 공식 문서의 OpenAI 호환 SDK 경로를 사용합니다.
+
+## 설치
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+그 뒤 `ugen` 명령을 사용할 수 있습니다.
+
+## 인증(비밀번호 입력 + 저장)
+
+토큰을 저장하려면 아래 명령을 사용하세요.
+
+```bash
+ugen auth --provider gemini
+ugen auth --provider openai
+ugen auth --provider grok
+```
+
+토큰 저장 후에는 생성 명령에서 자동으로 읽습니다.
+우선순위는 `환경변수 > 저장 토큰 > 즉시 비밀번호 입력` 입니다.
+
+- Gemini: `GEMINI_API_KEY` 또는 `GOOGLE_API_KEY`
+- OpenAI: `OPENAI_API_KEY`
+- Grok(xAI): `XAI_API_KEY`
+
+## 핵심 사용법
+
+모델 목록과 모델별 옵션 키 보기:
+
+```bash
+ugen models
+ugen models --provider gemini --modality video
+```
+
+이미지 생성(입력 순서 보장):
+
+```bash
+ugen generate image \
+  --provider openai \
+  --model gpt-image-1.5 \
+  --part text:"고양이 우주비행사" text:"필름 카메라 스타일" \
+  --option size=1024x1024 quality=high
+```
+
+이미지 + 텍스트 혼합 입력(여러 개, 순서 보장):
+
+```bash
+ugen generate image \
+  --provider gemini \
+  --model gemini-2.5-flash-image-preview \
+  --part text:"첫 이미지의 구도를 유지" image:./ref1.png text:"두 번째 이미지 색감을 반영" image:./ref2.jpg
+```
+
+동영상 생성:
+
+```bash
+ugen generate video \
+  --provider openai \
+  --model sora-2 \
+  --part text:"네온 도시를 달리는 고양이" image:./first-frame.png \
+  --option seconds=8 size=1280x720
+```
+
+고급 옵션(JSON) 병합:
+
+```bash
+ugen generate video \
+  --provider gemini \
+  --model veo-3.1-generate-preview \
+  --part text:"바닷가 일출 타임랩스" \
+  --options-json '{"numberOfVideos":1,"durationSeconds":8,"aspectRatio":"16:9"}'
+```
+
+## 옵션 구조
+
+- `--part <type:value...>`
+  - 반복 가능
+  - `text:...`, `image:/path/to/file` 지원
+  - 입력 순서는 그대로 모델 요청에 반영
+- `--option <key=value...>`
+  - 반복 가능
+  - 숫자/불리언/null 자동 파싱
+- `--options-json <json>`
+  - `--option` 위에 merge
+- 비디오 전용
+  - `--poll-interval-ms` (기본 `5000`)
+  - `--timeout-ms` (기본 `900000`)
+
+## 구현 메모
+
+- Gemini SDK: `@google/genai`
+- OpenAI SDK: `openai`
+- xAI(Grok): OpenAI 호환 SDK(base URL `https://api.x.ai/v1`)
+- 출력물: 기본 `./outputs`
+
+## npm 배포(Trusted Publish)
+
+- 워크플로우: `.github/workflows/publish.yml`
+
+Release(Published) 생성 시 OIDC 기반 trusted publish로 배포됩니다.
+
+## ugen 스킬 문서
+
+- 경로: `skills/ugen/SKILL.md`
+- 설치/인증/사용 흐름/트러블슈팅을 사용자 관점에서 정리한 가이드입니다.
+
+## 옵션 정보 출처(공식 문서)
+
+- Google GenAI SDK (`generateImages`, `generateVideos`, `generateContent`): https://www.npmjs.com/package/@google/genai
+- OpenAI TypeScript SDK (`images.generate/edit`, `videos.create/retrieve/downloadContent`): https://github.com/openai/openai-node
+- OpenAI Sora 모델/비디오 가이드: https://platform.openai.com/docs/models/sora-2
+- xAI API docs (OpenAI 호환 사용): https://docs.x.ai/docs/overview

package/dist/cli.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { MODEL_CATALOG } from './core/catalog.js';
+import { generateImage, generateVideo } from './core/generate.js';
+import { authAndStoreToken, getTokenFilePath, resolveApiKey } from './utils/auth.js';
+import { mergeOptions, parseOptionPairs } from './utils/options.js';
+import { parseParts } from './utils/parts.js';
+const program = new Command();
+program
+    .name('ugen')
+    .description('Gemini/OpenAI/Grok 이미지/비디오 생성 CLI')
+    .version('0.1.0');
+program
+    .command('models')
+    .description('지원 모델과 옵션 확인')
+    .option('-p, --provider <provider>', 'provider 필터 (gemini|openai|grok)')
+    .option('-m, --modality <modality>', 'modality 필터 (image|video)')
+    .action((opts) => {
+    const items = MODEL_CATALOG.filter((item) => (!opts.provider || item.provider === opts.provider) && (!opts.modality || item.modality === opts.modality));
+    if (items.length === 0) {
+        console.log('조건에 맞는 모델이 없습니다.');
+        return;
+    }
+    for (const item of items) {
+        console.log(`- [${item.provider}/${item.modality}] ${item.model}`);
+        console.log(`  입력지원: text=${item.supportsText}, image=${item.supportsImageInput}`);
+        console.log(`  옵션: ${item.options.join(', ')}`);
+        if (item.notes) {
+            console.log(`  비고: ${item.notes}`);
+        }
+    }
+});
+const generate = program.command('generate').description('콘텐츠 생성');
+program
+    .command('auth')
+    .description('provider 토큰을 비밀번호 입력으로 저장')
+    .requiredOption('-p, --provider <provider>', 'gemini|openai|grok')
+    .action(async (opts) => {
+    const provider = assertProvider(opts.provider);
+    await authAndStoreToken(provider);
+    console.log(`저장 완료: ${provider} 토큰`);
+    console.log(`저장 위치: ${getTokenFilePath()}`);
+});
+generate
+    .command('image')
+    .description('이미지 생성')
+    .requiredOption('-p, --provider <provider>', 'gemini|openai|grok')
+    .requiredOption('-m, --model <model>', '모델 ID')
+    .requiredOption('--part <part...>', '순서 보장 입력. 예: text:고양이 image:./cat.png text:배경은 숲')
+    .option('-o, --out <dir>', '출력 폴더', './outputs')
+    .option('--option <pair...>', '모델 옵션 key=value. 예: quality=high size=1024x1024')
+    .option('--options-json <json>', '모델 옵션 JSON 문자열')
+    .action(async (opts) => {
+    const provider = assertProvider(opts.provider);
+    const apiKey = await resolveApiKey(provider);
+    const parts = parseParts(opts.part);
+    const options = mergeOptions(parseOptionPairs(opts.option), opts.optionsJson);
+    const result = await generateImage({
+        provider,
+        model: normalizeModel(opts.model),
+        parts,
+        outDir: opts.out,
+        options
+    }, apiKey);
+    printResult(result);
+});
+generate
+    .command('video')
+    .description('동영상 생성')
+    .requiredOption('-p, --provider <provider>', 'gemini|openai|grok')
+    .requiredOption('-m, --model <model>', '모델 ID')
+    .requiredOption('--part <part...>', '순서 보장 입력. 예: text:광고 영상 image:./first-frame.png')
+    .option('-o, --out <dir>', '출력 폴더', './outputs')
+    .option('--option <pair...>', '모델 옵션 key=value. 예: seconds=8 size=1280x720')
+    .option('--options-json <json>', '모델 옵션 JSON 문자열')
+    .option('--poll-interval-ms <ms>', '상태 폴링 주기(ms)', '5000')
+    .option('--timeout-ms <ms>', '타임아웃(ms)', '900000')
+    .action(async (opts) => {
+    const provider = assertProvider(opts.provider);
+    const apiKey = await resolveApiKey(provider);
+    const parts = parseParts(opts.part);
+    const options = mergeOptions(parseOptionPairs(opts.option), opts.optionsJson);
+    const result = await generateVideo({
+        provider,
+        model: normalizeModel(opts.model),
+        parts,
+        outDir: opts.out,
+        options,
+        pollIntervalMs: Number(opts.pollIntervalMs),
+        timeoutMs: Number(opts.timeoutMs)
+    }, apiKey);
+    printResult(result);
+});
+program.parseAsync(process.argv).catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`오류: ${message}`);
+    process.exit(1);
+});
+function assertProvider(input) {
+    if (input === 'gemini' || input === 'openai' || input === 'grok') {
+        return input;
+    }
+    throw new Error(`지원하지 않는 provider: ${input}`);
+}
+function printResult(result) {
+    console.log(`완료: ${result.provider}/${result.modality}/${result.model}`);
+    if (result.outputs.length === 0) {
+        console.log('출력 파일이 없습니다. (모델 응답에 바이너리 결과 미포함)');
+    }
+    else {
+        for (const output of result.outputs) {
+            console.log(`- ${output}`);
+        }
+    }
+    if (result.meta) {
+        console.log(`meta: ${JSON.stringify(result.meta)}`);
+    }
+}
+function normalizeModel(model) {
+    const lowered = model.toLowerCase();
+    const fromCatalog = MODEL_CATALOG.find((item) => item.model.toLowerCase() === lowered);
+    return fromCatalog?.model ?? model;
+}

package/dist/core/catalog.js

@@ -0,0 +1,128 @@
+export const MODEL_CATALOG = [
+    {
+        provider: 'gemini',
+        modality: 'image',
+        model: 'gemini-3-pro-image-preview',
+        supportsText: true,
+        supportsImageInput: true,
+        options: ['responseModalities', 'temperature', 'topP', 'topK', 'seed']
+    },
+    {
+        provider: 'gemini',
+        modality: 'image',
+        model: 'gemini-2.5-flash-image-preview',
+        supportsText: true,
+        supportsImageInput: true,
+        options: ['responseModalities', 'temperature', 'topP', 'topK', 'seed']
+    },
+    {
+        provider: 'gemini',
+        modality: 'image',
+        model: 'imagen-4.0-generate-001',
+        supportsText: true,
+        supportsImageInput: false,
+        options: ['negativePrompt', 'numberOfImages', 'aspectRatio', 'guidanceScale', 'seed', 'outputMimeType', 'imageSize', 'enhancePrompt']
+    },
+    {
+        provider: 'gemini',
+        modality: 'image',
+        model: 'imagen-4.0-ultra-generate-001',
+        supportsText: true,
+        supportsImageInput: false,
+        options: ['negativePrompt', 'numberOfImages', 'aspectRatio', 'guidanceScale', 'seed', 'outputMimeType', 'imageSize', 'enhancePrompt']
+    },
+    {
+        provider: 'gemini',
+        modality: 'image',
+        model: 'imagen-4.0-fast-generate-001',
+        supportsText: true,
+        supportsImageInput: false,
+        options: ['negativePrompt', 'numberOfImages', 'aspectRatio', 'guidanceScale', 'seed', 'outputMimeType', 'imageSize', 'enhancePrompt']
+    },
+    {
+        provider: 'openai',
+        modality: 'image',
+        model: 'gpt-image-1.5',
+        supportsText: true,
+        supportsImageInput: true,
+        options: ['background', 'moderation', 'n', 'output_format', 'output_compression', 'quality', 'size', 'stream']
+    },
+    {
+        provider: 'openai',
+        modality: 'image',
+        model: 'gpt-image-1',
+        supportsText: true,
+        supportsImageInput: true,
+        options: ['background', 'moderation', 'n', 'output_format', 'output_compression', 'quality', 'size', 'stream', 'input_fidelity']
+    },
+    {
+        provider: 'openai',
+        modality: 'image',
+        model: 'gpt-image-1-mini',
+        supportsText: true,
+        supportsImageInput: true,
+        options: ['background', 'moderation', 'n', 'output_format', 'output_compression', 'quality', 'size', 'stream']
+    },
+    {
+        provider: 'grok',
+        modality: 'image',
+        model: 'grok-imagine-image',
+        supportsText: true,
+        supportsImageInput: true,
+        options: ['n', 'output_format', 'quality', 'size'],
+        notes: 'xAI는 OpenAI 호환 SDK 경로를 사용'
+    },
+    {
+        provider: 'grok',
+        modality: 'image',
+        model: 'grok-imagine-image-pro',
+        supportsText: true,
+        supportsImageInput: true,
+        options: ['n', 'output_format', 'quality', 'size'],
+        notes: 'xAI는 OpenAI 호환 SDK 경로를 사용'
+    },
+    {
+        provider: 'gemini',
+        modality: 'video',
+        model: 'veo-3.1-generate-preview',
+        supportsText: true,
+        supportsImageInput: true,
+        options: ['numberOfVideos', 'fps', 'durationSeconds', 'seed', 'aspectRatio', 'resolution', 'negativePrompt', 'enhancePrompt', 'generateAudio']
+    },
+    {
+        provider: 'gemini',
+        modality: 'video',
+        model: 'veo-3.1-fast-generate-preview',
+        supportsText: true,
+        supportsImageInput: true,
+        options: ['numberOfVideos', 'fps', 'durationSeconds', 'seed', 'aspectRatio', 'resolution', 'negativePrompt', 'enhancePrompt', 'generateAudio']
+    },
+    {
+        provider: 'openai',
+        modality: 'video',
+        model: 'sora-2',
+        supportsText: true,
+        supportsImageInput: true,
+        options: ['seconds', 'size']
+    },
+    {
+        provider: 'openai',
+        modality: 'video',
+        model: 'sora-2-pro',
+        supportsText: true,
+        supportsImageInput: true,
+        options: ['seconds', 'size']
+    },
+    {
+        provider: 'grok',
+        modality: 'video',
+        model: 'grok-imagine-video',
+        supportsText: true,
+        supportsImageInput: true,
+        options: ['seconds', 'size'],
+        notes: 'xAI는 OpenAI 호환 SDK 경로를 사용'
+    }
+];
+export function getModelItem(provider, modality, model) {
+    return MODEL_CATALOG.find((item) => item.provider === provider && item.modality === modality && item.model === model);
+}

package/dist/core/generate.js

@@ -0,0 +1,28 @@
+import { generateImageWithGemini, generateVideoWithGemini } from '../providers/gemini.js';
+import { generateImageWithOpenAILike, generateVideoWithOpenAILike } from '../providers/openaiLike.js';
+export async function generateImage(req, apiKey) {
+    if (req.provider === 'gemini') {
+        return generateImageWithGemini(req, apiKey);
+    }
+    if (req.provider === 'openai') {
+        return generateImageWithOpenAILike(req, { provider: 'openai', apiKey });
+    }
+    return generateImageWithOpenAILike(req, {
+        provider: 'grok',
+        apiKey,
+        baseURL: 'https://api.x.ai/v1'
+    });
+}
+export async function generateVideo(req, apiKey) {
+    if (req.provider === 'gemini') {
+        return generateVideoWithGemini(req, apiKey);
+    }
+    if (req.provider === 'openai') {
+        return generateVideoWithOpenAILike(req, { provider: 'openai', apiKey });
+    }
+    return generateVideoWithOpenAILike(req, {
+        provider: 'grok',
+        apiKey,
+        baseURL: 'https://api.x.ai/v1'
+    });
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/providers/gemini.js

@@ -0,0 +1,124 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { GoogleGenAI, createPartFromUri } from '@google/genai';
+import { detectMimeTypeFromPath, fileExists, writeBase64File } from '../utils/io.js';
+import { imageParts, joinTextParts } from '../utils/parts.js';
+export async function generateImageWithGemini(req, apiKey) {
+    const ai = new GoogleGenAI({ apiKey });
+    const text = joinTextParts(req.parts);
+    const images = imageParts(req.parts);
+    if (req.model.startsWith('imagen-')) {
+        if (!text) {
+            throw new Error('Imagen 계열은 text 파트가 필요합니다.');
+        }
+        if (images.length > 0) {
+            throw new Error(`${req.model}은 이 CLI에서 text-to-image만 지원합니다. (image 입력 불가)`);
+        }
+        const response = await ai.models.generateImages({
+            model: req.model,
+            prompt: text,
+            config: req.options
+        });
+        const outputs = [];
+        for (const image of response.generatedImages ?? []) {
+            const b64 = image.image?.imageBytes;
+            if (!b64)
+                continue;
+            const mime = req.options.outputMimeType ?? 'image/png';
+            const ext = mime === 'image/jpeg' ? 'jpg' : mime === 'image/webp' ? 'webp' : 'png';
+            outputs.push(await writeBase64File(b64, req.outDir, 'gemini-image', ext));
+        }
+        return { provider: 'gemini', model: req.model, modality: 'image', outputs };
+    }
+    const contentParts = [];
+    for (const part of req.parts) {
+        if (part.type === 'text') {
+            contentParts.push({ text: part.value });
+            continue;
+        }
+        if (!(await fileExists(part.value))) {
+            throw new Error(`이미지 파일을 찾을 수 없습니다: ${part.value}`);
+        }
+        const uploaded = await ai.files.upload({ file: part.value });
+        if (!uploaded.uri || !uploaded.mimeType) {
+            throw new Error(`Gemini 파일 업로드 결과에 uri/mimeType이 없습니다: ${part.value}`);
+        }
+        contentParts.push(createPartFromUri(uploaded.uri, uploaded.mimeType));
+    }
+    const response = await ai.models.generateContent({
+        model: req.model,
+        contents: [{ role: 'user', parts: contentParts }],
+        config: {
+            responseModalities: ['IMAGE', 'TEXT'],
+            ...req.options
+        }
+    });
+    const outputs = [];
+    const candidates = response.candidates ?? [];
+    for (const candidate of candidates) {
+        const parts = candidate?.content?.parts ?? [];
+        for (const part of parts) {
+            const b64 = part?.inlineData?.data;
+            const mime = part?.inlineData?.mimeType;
+            if (!b64)
+                continue;
+            const ext = mime === 'image/jpeg' ? 'jpg' : mime === 'image/webp' ? 'webp' : 'png';
+            outputs.push(await writeBase64File(b64, req.outDir, 'gemini-image', ext));
+        }
+    }
+    return { provider: 'gemini', model: req.model, modality: 'image', outputs };
+}
+export async function generateVideoWithGemini(req, apiKey) {
+    const ai = new GoogleGenAI({ apiKey });
+    const text = joinTextParts(req.parts);
+    const images = imageParts(req.parts);
+    if (!text && images.length === 0) {
+        throw new Error('Gemini 비디오는 text 또는 image 입력이 필요합니다.');
+    }
+    if (images.length > 1) {
+        throw new Error('Gemini 비디오는 현재 이미지 입력 1개만 지원합니다.');
+    }
+    const source = {};
+    if (text)
+        source.prompt = text;
+    if (images[0]) {
+        if (!(await fileExists(images[0]))) {
+            throw new Error(`이미지 파일을 찾을 수 없습니다: ${images[0]}`);
+        }
+        const bytes = await fs.readFile(images[0]);
+        source.image = {
+            imageBytes: bytes.toString('base64'),
+            mimeType: await detectMimeTypeFromPath(images[0])
+        };
+    }
+    let operation = await ai.models.generateVideos({
+        model: req.model,
+        source,
+        config: req.options
+    });
+    const started = Date.now();
+    while (!operation.done) {
+        if (Date.now() - started > req.timeoutMs) {
+            throw new Error('Gemini 비디오 생성 대기 시간이 초과되었습니다. --timeout-ms를 늘려주세요.');
+        }
+        await new Promise((resolve) => setTimeout(resolve, req.pollIntervalMs));
+        operation = await ai.operations.getVideosOperation({ operation });
+    }
+    const generated = operation.response?.generatedVideos ?? [];
+    if (generated.length === 0) {
+        throw new Error('Gemini 비디오 생성 결과가 비어 있습니다.');
+    }
+    const outputs = [];
+    for (let i = 0; i < generated.length; i += 1) {
+        const downloadPath = path.resolve(req.outDir, `gemini-video-${Date.now()}-${i + 1}.mp4`);
+        await ai.files.download({ file: generated[i], downloadPath });
+        outputs.push(downloadPath);
+    }
+    return {
+        provider: 'gemini',
+        model: req.model,
+        modality: 'video',
+        outputs,
+        meta: { operationName: operation.name }
+    };
+}

package/dist/providers/openaiLike.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import OpenAI from 'openai';
+import { imageParts, joinTextParts } from '../utils/parts.js';
+import { fileExists, writeBase64File, writeBufferFile } from '../utils/io.js';
+function makeClient(config) {
+    return new OpenAI({
+        apiKey: config.apiKey,
+        baseURL: config.baseURL
+    });
+}
+export async function generateImageWithOpenAILike(req, config) {
+    const client = makeClient(config);
+    const prompt = joinTextParts(req.parts);
+    const images = imageParts(req.parts);
+    if (!prompt) {
+        throw new Error('이미지 생성에는 최소 1개의 text 파트가 필요합니다.');
+    }
+    if (images.length === 0) {
+        const result = await client.images.generate({
+            model: req.model,
+            prompt,
+            ...req.options
+        });
+        const outputs = [];
+        for (const image of result.data ?? []) {
+            if (!image.b64_json)
+                continue;
+            const ext = (req.options.output_format ?? 'png').replace('jpeg', 'jpg');
+            outputs.push(await writeBase64File(image.b64_json, req.outDir, `${config.provider}-image`, ext));
+        }
+        return { provider: config.provider, model: req.model, modality: 'image', outputs };
+    }
+    const uploadables = [];
+    for (const imagePath of images) {
+        if (!(await fileExists(imagePath))) {
+            throw new Error(`이미지 파일을 찾을 수 없습니다: ${imagePath}`);
+        }
+        uploadables.push(fs.createReadStream(imagePath));
+    }
+    const edited = await client.images.edit({
+        model: req.model,
+        prompt,
+        image: uploadables,
+        ...req.options
+    });
+    const outputs = [];
+    for (const image of edited.data ?? []) {
+        if (!image.b64_json)
+            continue;
+        const ext = (req.options.output_format ?? 'png').replace('jpeg', 'jpg');
+        outputs.push(await writeBase64File(image.b64_json, req.outDir, `${config.provider}-image`, ext));
+    }
+    return { provider: config.provider, model: req.model, modality: 'image', outputs };
+}
+export async function generateVideoWithOpenAILike(req, config) {
+    const client = makeClient(config);
+    const prompt = joinTextParts(req.parts);
+    const images = imageParts(req.parts);
+    if (!prompt) {
+        throw new Error('동영상 생성에는 최소 1개의 text 파트가 필요합니다.');
+    }
+    if (images.length > 1) {
+        throw new Error('OpenAI/xAI 비디오는 현재 이미지 참조 1개만 지원합니다.');
+    }
+    const createReq = {
+        model: req.model,
+        prompt,
+        ...req.options
+    };
+    if (images[0]) {
+        if (!(await fileExists(images[0]))) {
+            throw new Error(`이미지 파일을 찾을 수 없습니다: ${images[0]}`);
+        }
+        createReq.input_reference = fs.createReadStream(images[0]);
+    }
+    let job = await client.videos.create(createReq);
+    const started = Date.now();
+    while (job.status !== 'completed') {
+        if (job.status === 'failed') {
+            throw new Error(`비디오 생성 실패: ${job.error?.message ?? '알 수 없는 오류'}`);
+        }
+        if (Date.now() - started > req.timeoutMs) {
+            throw new Error('비디오 생성 대기 시간이 초과되었습니다. --timeout-ms를 늘려주세요.');
+        }
+        await new Promise((resolve) => setTimeout(resolve, req.pollIntervalMs));
+        job = await client.videos.retrieve(job.id);
+    }
+    const response = await client.videos.downloadContent(job.id, { variant: 'video' });
+    const arrayBuffer = await response.arrayBuffer();
+    const outputPath = await writeBufferFile(Buffer.from(arrayBuffer), req.outDir, `${config.provider}-video`, 'mp4');
+    return {
+        provider: config.provider,
+        model: req.model,
+        modality: 'video',
+        outputs: [outputPath],
+        meta: { jobId: job.id }
+    };
+}