Formerly KrillinAI, VideoTranslation and Dubbing Tool for 120+ Languages. Open-source AI workspace for creators, powered by Codex. Video downloader, video translation, create videos, images, audios, and edits with Agents in one place. For your Social Media like YouTube, TikTok, Instagram, etc.
TypeScript agent-skillscodex-clideskop-appdubbingimage-generationlocalizationskillsttsvideo-editingvideo-generationvideo-transcriptionvideo-translation
import {
createDefaultCreatorServicesConfig,
type CreatorJob,
type CreatorStageRun,
type ImageGenerationProvider
} from '@opencreator/protocol';
import { access, copyFile, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { afterEach, describe, expect, it, vi } from 'vitest';
import type { CreatorExecutorInput } from '../../src/creator/executor.js';
import { createImageExecutor } from '../../src/creator/image/executor.js';
import { ImageGenerationProviderError } from '../../src/image-generation/provider.js';
let tempDir = '';
afterEach(async () => {
if (tempDir) await rm(tempDir, { recursive: true, force: true });
tempDir = '';
});
describe('creator image executor', () => {
it('saves all four images in a batch without submitting four paid requests', async () => {
tempDir = await mkdtemp(join(tmpdir(), 'creator-image-batch-'));
const contents = Array.from({ length: 4 }, (_, i) => ({ content: png(`batch-${i}`), mime: 'image/png' as const }));
const generate = vi.fn(async () => ({ model: 'midjourney-v8.2', contents }));
const executor = createImageExecutor({ configStore: { read: async () => createDefaultCreatorServicesConfig() }, generate });
const result = await executor.run(stageInput({ candidateCount: 1 }));
expect(generate).toHaveBeenCalledTimes(1);
expect(result.outputs).toHaveLength(4);
expect(new Set(result.outputs.map(output => output.path)).size).toBe(4);
for (const [i, output] of result.outputs.entries()) {
expect(await readFile(output.path!)).toEqual(contents[i]!.content);
expect(output.metadata).toMatchObject({ candidate: i + 1, model: 'midjourney-v8.2' });
}
expect(result.progress).toMatchObject({ status: 'succeeded', completed: 4, failed: 0, total: 4 });
});
it.each(['openai', 'codex-native'] as const)('rejects a missing required image before invoking %s', async provider => {
const generate = vi.fn();
const executor = createImageExecutor({ configStore: { read: async () => createDefaultCreatorServicesConfig() }, generate });
await expect(executor.run(stageInput({ provider, prompt: '以上传的人物照片为唯一主体,生成复古海报。' }))).rejects.toMatchObject({
code: 'creator_stage_input_missing', publicFacts: { kind: 'validation', upstreamCode: 'IMAGE_REFERENCE_MISSING' }
});
expect(generate).not.toHaveBeenCalled();
});
it('preserves provider diagnostics when all image candidates fail', async () => {
const publicFacts = { kind: 'http-rejected' as const, provider: 'openai', httpStatus: 400,
upstreamCode: 'invalid_image', upstreamMessage: 'Reference image is invalid', requestId: 'request-123' };
const cause = new ImageGenerationProviderError('upstream_error', 'Reference image is invalid', publicFacts);
const executor = createImageExecutor({
configStore: { read: async () => createDefaultCreatorServicesConfig() },
generate: vi.fn(async () => { throw cause; })
});
await expect(executor.run(stageInput({ candidateCount: 1 }))).rejects.toMatchObject({
code: 'image_generation_failed', publicFacts, cause
});
});
it.each(['openai', 'jimeng', 'kling', 'gemini'] as const)(
'creates generated_image artifacts with %s metadata',
async provider => {
tempDir = await mkdtemp(join(tmpdir(), 'creator-image-executor-'));
const config = createDefaultCreatorServicesConfig();
const generate = vi.fn(async (request: { provider: ImageGenerationProvider }) => ({
model: `${request.provider}-model`,
contents: [{ content: png(`image-${request.provider}`), mime: 'image/png' as const }]
}));
const executor = createImageExecutor({
configStore: { read: async () => config },
generate: generate as never
});
const stage = stageInput({
provider,
candidateCount: 2,
size: '1536x1024',
quality: 'high'
});
const result = await executor.run(stage);
expect(generate).toHaveBeenCalledTimes(2);
expect(generate).toHaveBeenCalledWith(
expect.objectContaining({ provider, count: 1 }),
config,
expect.objectContaining({ signal: expect.any(AbortSignal) })
);
expect(result.outputs).toHaveLength(2);
expect(result.outputs[0]).toMatchObject({
kind: 'generated_image',
status: 'completed',
metadata: {
provider,
model: `${provider}-model`,
candidate: 1,
imageSize: '1536x1024',
quality: 'high',
mimeType: 'image/png'
}
});
expect(result.progress).toMatchObject({
status: 'succeeded',
phase: 'completed',
percent: 100,
completed: 2,
failed: 0,
total: 2
});
expect(stage.reportProgress).toHaveBeenNthCalledWith(1, {
status: 'running',
phase: 'validating',
percent: 5
});
expect(stage.reportProgress).toHaveBeenNthCalledWith(2, {
status: 'running',
phase: 'generating_candidates',
percent: 10,
completed: 0,
failed: 0,
total: 2
});
expect(stage.reportProgress).toHaveBeenLastCalledWith({
status: 'succeeded',
phase: 'completed',
percent: 100,
completed: 2,
failed: 0,
total: 2
});
}
);
it('runs exactly one candidate for codex-native', async () => {
tempDir = await mkdtemp(join(tmpdir(), 'creator-image-executor-codex-native-'));
const config = createDefaultCreatorServicesConfig();
const generate = vi.fn(async (request: { provider: ImageGenerationProvider }) => ({
model: `${request.provider}-model`,
contents: [{ content: png('image-codex-native'), mime: 'image/png' as const }]
}));
const executor = createImageExecutor({
configStore: { read: async () => config },
generate: generate as never
});
const result = await executor.run(stageInput({
provider: 'codex-native',
candidateCount: 1
}));
expect(generate).toHaveBeenCalledTimes(1);
expect(generate).toHaveBeenCalledWith(
expect.objectContaining({ provider: 'codex-native', count: 1 }),
config,
expect.objectContaining({ signal: expect.any(AbortSignal) })
);
expect(result.outputs).toHaveLength(1);
});
it('forwards manual image model controls from drafts to the provider and saved artifact', async () => {
tempDir = await mkdtemp(join(tmpdir(), 'creator-image-model-options-'));
const config = createDefaultCreatorServicesConfig();
const generate = vi.fn(async () => ({ model: 'gpt-image-2', contents: [{ content: png('image'), mime: 'image/png' as const }] }));
const executor = createImageExecutor({ configStore: { read: async () => config }, generate });
const result = await executor.run(stageInput({ provider: 'openai', candidateCount: 1, aspectRatio: '16:9', resolution: '2K', modelQuality: 'auto' }));
expect(generate).toHaveBeenCalledWith(expect.objectContaining({ aspectRatio: '16:9', resolution: '2K', modelQuality: 'auto' }), config, expect.any(Object));
expect(result.outputs[0]?.metadata).toMatchObject({ aspectRatio: '16:9', resolution: '2K', modelQuality: 'auto' });
});
it('normalizes inherited candidate counts for codex-native', async () => {
tempDir = await mkdtemp(join(tmpdir(), 'creator-image-executor-codex-native-many-'));
const config = createDefaultCreatorServicesConfig();
config.image.provider = 'codex-native';
const generate = vi.fn(async () => ({
model: 'codex-native',
contents: [{ content: png('normalized-codex-image'), mime: 'image/png' as const }]
}));
const executor = createImageExecutor({
configStore: { read: async () => config },
generate: generate as never
});
const stage = stageInput({ candidateCount: 2 });
delete stage.job.state.provider;
await executor.run(stage);
expect(generate).toHaveBeenCalledWith(
expect.objectContaining({ provider: 'codex-native', count: 1 }),
config,
expect.any(Object)
);
});
it('keeps successful candidates when another candidate fails', async () => {
tempDir = await mkdtemp(join(tmpdir(), 'creator-image-executor-partial-'));
let candidate = 0;
const executor = createImageExecutor({
configStore: { read: async () => createDefaultCreatorServicesConfig() },
generate: vi.fn(async () => {
candidate += 1;
if (candidate === 2) throw new Error('candidate failed');
return {
model: 'gpt-image-test',
contents: [{ content: png(`candidate-${candidate}`), mime: 'image/png' as const }]
};
}) as never
});
const result = await executor.run(stageInput({ candidateCount: 2 }));
expect(result.outputs).toHaveLength(1);
expect(result.progress).toMatchObject({
status: 'partial_success',
phase: 'completed',
percent: 100,
completed: 1,
failed: 1,
failures: [{ candidate: 2, message: 'candidate failed' }]
});
});
it.each([
['custom', 'Stack the headline in exactly three lines.', true],
['custom', '', false],
['personal-growth', 'Stack the headline in exactly three lines.', false]
] as const)('respects explicit line layouts only for %s styles with instructions %s', async (coverStyle, customStylePrompt, preservesLayout) => {
tempDir = await mkdtemp(join(tmpdir(), 'creator-cover-text-layout-'));
const generate = vi.fn(async () => ({
model: 'gpt-image-test',
contents: [{ content: png('cover'), mime: 'image/png' as const }]
}));
const executor = createImageExecutor({
configStore: { read: async () => createDefaultCreatorServicesConfig() },
generate: generate as never
});
await executor.run(stageInput({
coverStyle,
customStylePrompt,
coverHeadline: 'images go hard',
resolvedCoverTextLanguage: 'en-US'
}, { templateId: 'cover', templateVersion: 2 }));
const prompt = (generate.mock.calls as unknown as Array<[{ prompt: string }]>)[0]![0].prompt;
expect(prompt).toContain('Headline: "images go hard"');
expect(prompt).toContain('English (en-US)');
expect(prompt.includes('preserve any headline line layout explicitly requested')).toBe(preservesLayout);
if (preservesLayout) {
expect(prompt).toContain(customStylePrompt);
expect(prompt).not.toContain('Keep text clear of the main subject, use at most two headline lines');
} else {
expect(prompt).toContain('Keep text clear of the main subject, use at most two headline lines');
}
});
it('normalizes cover artifacts to the exact selected ratio', async () => {
tempDir = await mkdtemp(join(tmpdir(), 'creator-cover-normalize-'));
const normalizeCoverImage = vi.fn(async (input: {
sourcePath: string;
outputPath: string;
ratio: string;
}) => {
await copyFile(input.sourcePath, input.outputPath);
return { width: 1536, height: 864 };
});
const executor = createImageExecutor({
configStore: { read: async () => createDefaultCreatorServicesConfig() },
generate: vi.fn(async () => ({
model: 'gpt-image-test',
contents: [{ content: png('cover'), mime: 'image/png' as const }]
})) as never,
normalizeCoverImage
});
const result = await executor.run(stageInput({ ratio: '16:9' }, {
templateId: 'cover',
templateVersion: 2
}));
expect(normalizeCoverImage).toHaveBeenCalledWith(expect.objectContaining({
ratio: '16:9',
sourcePath: expect.stringContaining('-source.png'),
outputPath: expect.stringMatching(/OpenCreator-image-1\.png$/),
signal: expect.any(AbortSignal)
}));
expect(result.outputs[0]).toMatchObject({
kind: 'cover_image',
metadata: {
ratio: '16:9',
normalizedToRatio: true,
width: 1536,
height: 864
}
});
await expect(access(normalizeCoverImage.mock.calls[0]![0].sourcePath))
.rejects.toMatchObject({ code: 'ENOENT' });
});
it('passes a registered reference image to supported cover generation', async () => {
tempDir = await mkdtemp(join(tmpdir(), 'creator-cover-reference-'));
const referencePath = join(tempDir, 'reference.png');
const keyframePath = join(tempDir, 'source-thumbnail.png');
await writeFile(referencePath, png('reference'));
await writeFile(keyframePath, png('source-keyframe'));
const config = createDefaultCreatorServicesConfig();
const generate = vi.fn(async () => ({
model: 'gpt-image-test',
contents: [{ content: png('cover'), mime: 'image/png' as const }]
}));
const executor = createImageExecutor({
configStore: { read: async () => config },
generate: generate as never
});
const input = stageInput({}, {
templateId: 'cover',
templateVersion: 2,
artifacts: [
{
id: 'source_keyframe_1',
jobId: 'image_job',
kind: 'source_keyframe',
version: 1,
status: 'completed',
path: keyframePath,
scopeKey: null,
inputFingerprint: null,
sha256: null,
sourceArtifactIds: [],
metadata: {},
createdAt: '2026-08-26T00:00:00.000Z'
},
{
id: 'reference_1',
jobId: 'image_job',
kind: 'reference_image',
version: 1,
status: 'completed',
path: referencePath,
scopeKey: null,
inputFingerprint: null,
sha256: null,
sourceArtifactIds: [],
metadata: {},
createdAt: '2026-08-26T00:00:01.000Z'
}
]
});
input.job.state.sourceType = 'youtube';
input.job.state.coverHeadline = '参考图测试';
input.inputArtifacts = input.job.artifacts;
const result = await executor.run(input);
expect(generate).toHaveBeenCalledWith(
expect.objectContaining({
prompt: expect.stringMatching(
/finished, publication-ready video thumbnail[\s\S]*user-provided image[\s\S]*A bright creative studio/
)
}),
config,
expect.objectContaining({
referenceImage: {
content: png('reference'),
mime: 'image/png'
}
})
);
expect(result.outputs[0]?.metadata).toMatchObject({
referenceArtifactId: 'reference_1',
referenceArtifactKind: 'reference_image',
coverStyle: 'bilibili-red-blue-white',
coverTextLanguage: 'zh-CN'
});
});
it('uses the YouTube source thumbnail when no uploaded reference is selected', async () => {
tempDir = await mkdtemp(join(tmpdir(), 'creator-cover-youtube-reference-'));
const keyframePath = join(tempDir, 'source-thumbnail.png');
await writeFile(keyframePath, png('source-keyframe'));
const config = createDefaultCreatorServicesConfig();
const generate = vi.fn(async () => ({
model: 'gpt-image-test',
contents: [{ content: png('cover'), mime: 'image/png' as const }]
}));
const executor = createImageExecutor({
configStore: { read: async () => config },
generate: generate as never
});
const input = stageInput({
sourceType: 'youtube'
}, {
templateId: 'cover',
templateVersion: 2,
artifacts: [
{
id: 'cover_brief_1',
jobId: 'image_job',
kind: 'cover_brief',
version: 1,
status: 'completed',
path: join(tempDir, 'cover-brief.json'),
scopeKey: null,
inputFingerprint: null,
sha256: null,
sourceArtifactIds: [],
metadata: {
headline: '真正拉开差距的习惯',
subheadline: '停止内耗,开始持续成长',
emphasisTerms: ['习惯', '持续成长'],
language: 'zh-CN'
},
createdAt: '2026-08-26T00:00:00.000Z'
},
{
id: 'source_keyframe_1',
jobId: 'image_job',
kind: 'source_keyframe',
version: 1,
status: 'completed',
path: keyframePath,
scopeKey: null,
inputFingerprint: null,
sha256: null,
sourceArtifactIds: [],
metadata: {},
createdAt: '2026-08-26T00:00:01.000Z'
}
]
});
input.job.state.coverStyle = 'wealth-platinum-red';
input.job.state.resolvedCoverTextLanguage = 'zh-CN';
input.inputArtifacts = input.job.artifacts;
const result = await executor.run(input);
expect(generate).toHaveBeenCalledWith(
expect.objectContaining({
prompt: expect.stringMatching(
/one image-generation pass[\s\S]*original YouTube thumbnail[\s\S]*真正拉开差距的习惯[\s\S]*停止内耗,开始持续成长[\s\S]*white, platinum, charcoal, and strong red/
)
}),
config,
expect.objectContaining({
referenceImage: {
content: png('source-keyframe'),
mime: 'image/png'
}
})
);
expect(result.outputs[0]?.metadata).toMatchObject({
referenceArtifactId: 'source_keyframe_1',
referenceArtifactKind: 'source_keyframe',
coverStyle: 'wealth-platinum-red',
coverTextLanguage: 'zh-CN',
headline: '真正拉开差距的习惯',
subheadline: '停止内耗,开始持续成长',
emphasisTerms: ['习惯', '持续成长']
});
const prompt = (
generate.mock.calls as unknown as Array<[{ prompt: string }]>
)[0]?.[0].prompt ?? '';
expect(prompt).toContain('Do not return a text-free background');
expect(prompt).not.toContain('young man');
});
});
function stageInput(
state: Record<string, string | number>,
jobPatch: Partial<CreatorJob> = {}
): CreatorExecutorInput {
const createdAt = '2026-08-26T00:00:00.000Z';
const job: CreatorJob = {
id: 'image_job',
projectId: 'project_1',
templateId: jobPatch.templateId ?? 'image-generation',
templateVersion: jobPatch.templateVersion ?? 1,
status: 'running',
revision: 1,
presetOrigin: null,
state: {
prompt: 'A bright creative studio',
provider: 'openai',
size: '1024x1024',
quality: 'medium',
candidateCount: 1,
currentStage: 'generate',
...state
},
agentThreadId: null,
stages: [],
artifacts: jobPatch.artifacts ?? [],
providerRequests: [],
activities: [],
createdAt,
updatedAt: createdAt
};
const stageRun: CreatorStageRun = {
id: 'image_stage',
jobId: job.id,
stageId: 'generate',
executor: 'image',
status: 'running',
dispatchStatus: 'claimed',
claimOwner: 'test',
claimExpiresAt: null,
attempt: 1,
idempotencyKey: null,
scopeKey: null,
inputFingerprint: null,
progress: {},
errorCode: null,
errorMessage: null,
startedAt: createdAt,
finishedAt: null
};
return {
stageRun,
job,
inputArtifacts: [],
workdir: tempDir,
signal: new AbortController().signal,
reportProgress: vi.fn()
};
}
function png(label: string): Buffer {
return Buffer.concat([
Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
Buffer.from(label.padEnd(16, '.'))
]);
}