Generate AI images

POST /api/v1/creative-hub/generate/image (verified apps/backend/src/routes/api/creative-hub-generate.route.ts). Three providers verified in apps/backend/src/providers/creative/types.ts: flux_2_pro (default, photoreal + product), gpt_image_1_5 (text-aware), seedream_4_5 (stylized + artistic). Params: prompt (required), width (default 1024), height (default 1024), num_variants (default 1). Async via generate-image.worker.ts; result URLs stored in creative_job.result_urls JSON array.

Who is this for

Mediabuyers needing static images for ads — product shots, lifestyle scenes, poster-style designs.

The 3 providers

flux_2_pro (default)

Best for: photorealistic images, product photography, lifestyle scenes.

Strengths:

• High photo realism

• Good at composition + lighting

• Default choice for product ads

Weaknesses:

• Limited text-on-image (asks to render copy = often garbled)

gpt_image_1_5

Best for: posters with text on image, designs that need readable copy embedded.

Strengths:

• Renders text legibly (much better than other providers)

• Good for "Sale 50% off" type posters

Weaknesses:

• Slightly less photoreal than Flux

seedream_4_5

Best for: stylized + artistic, illustrative, conceptual ads.

Strengths:

• Distinctive artistic style

• Good for brand-led campaigns that want non-photo aesthetic

Weaknesses:

• Less suitable for product photography expectations

How to generate

Step 1: Open the generator

/creative-hub → top toolbar → AI Generate → Image tab.

Or from within a folder → Generate here → Image.

Step 2: Pick a provider

Dropdown (default flux_2_pro). Pick per use case (see provider guidance above).

Step 3: Write the prompt

Text field. Be specific. Include:

• Subject (what's in frame)

• Action / pose

• Style (photoreal / illustration / cinematic / etc.)

• Framing (close-up / medium / wide)

• Lighting (natural / studio / golden hour)

Example: "A product shot of a sleek black wireless headphone on a marble surface, studio lighting, soft shadow, hero composition, ultra-detailed."

Step 4: Set dimensions

width × height in pixels.

Common dimensions:

Larger dimensions cost more credits + take longer.

Step 5: Pick num_variants

How many variations to generate from the same prompt. Default 1, max varies by provider (typically 1-4).

For exploration: 3-4 variants. For locked concepts: 1.

Step 6: Submit

Click Generate. POST /api/v1/creative-hub/generate/image runs.

Returns 202 Accepted + {job_id, status: "pending"}.

Step 7: Track + download

UI shows the job in the Jobs panel. Status progresses pending → processing → completed (typically 10-60 sec).

Once completed: click the job → preview + download. Files also added to your Creative Hub folder automatically.

Endpoint

POST /api/v1/creative-hub/generate/image (verified).

Body:

• prompt (required)

• provider (optional, default flux_2_pro)

• width, height (optional, default 1024)

• num_variants (optional, default 1)

• folder_id (optional, target folder for output)

Returns:

• 202 Accepted

• {job_id, status: "pending"}

Poll GET /api/v1/creative-hub/jobs/:job_id.

Cost

Cost depends on provider + dimensions + num_variants. Recorded in creative_job.cost_cents. See ch-112 AI credits.

Prompt engineering tips

Be specific over general

• Bad: "a person using a laptop"

• Good: "a young professional woman in a sunlit cafe, working on a silver laptop, focused expression, candid composition, shallow depth of field"

Specify what NOT to include

• Some providers support negative prompts. Use them: "no text, no watermark, no logos, no people in background"

Match aspect ratio to placement

• Generate 1080 × 1920 for Reels — not square then crop. Crop loses composition.

Iterate, don't over-tune one prompt

• 3 variants of "version 1" is faster than 1 variant of "version 17"

• Pick the best variant + iterate from there

Use real product images as input where possible

• For product-shot replacements: pair with ch-117 compositing to overlay real product on AI-generated background

Common mistakes

• Asking for text in flux_2_pro: switch to gpt_image_1_5

• Generating square then cropping for Reels: generate 9:16 directly

• Vague prompts: specificity = consistency

• Forgetting to set folder_id: outputs land in root; harder to organize later

• Generating 8 variants when 3 would do: wastes credits

Common issues

• Generation rejected (content moderation): prompt triggered provider's safety filter. Reword without sensitive terms. Failed jobs are free.

• Result doesn't match prompt: try the same prompt with another provider (e.g. switch flux → gpt_image)

• Generation stuck "processing" > 5 min: rare; usually self-resolves. If persistent, check ch-128.

• Variants look identical: provider's seed handling; try slight prompt variations across variants

Related

• Generate videos — the video equivalent

• Manage AI jobs — track + download

• AI best practices — broader guidance