Image Generation

Overview

The production flow uses Kie.ai GPT Image 2 to combine two distinct, account-owned reference photos into one engagement portrait.

Endpoint

POST /api/image/generate

Request

{
  "imageUrl": "https://media.example.com/uploads/user/person-a.jpg",
  "partnerImageUrl": "https://media.example.com/uploads/user/person-b.jpg",
  "styleKey": "editorial",
  "customPrompt": "Optional scene details"
}

Both URLs must belong to the signed-in account. The server validates the style and builds the provider prompt.

Response Flow

1. Validate user session and credits
2. Reserve one credit and create a processing history record in one transaction
3. Send both source images to Kie.ai GPT Image 2
4. Apply a server-side watermark for trial previews and upload the result to R2
5. Save to generationHistory table
6. Return the image URL and remaining balance; refund the credit on provider or storage failure

Storage

R2 is required for the engagement flow. Provider URLs are mirrored immediately so generation history never depends on an expiring third-party result URL.

History

All generations are tracked in the generationHistory table:

• type — image
• prompt — User's prompt
• resultUrl — URL of generated image
• status — completed or failed
• creditsUsed — Credits charged