Generate Product Marketing Post (v1)
Method & Path
POST /api/v1/workspace/:workspaceId/storefront/products/:productId/generate-post
Description
Generates marketing post text (and optional AI image) for a storefront product, stores the result, and creates storefront marketing-post entries linked to the product.
Authentication
Required: Workspace staff auth with permission store.products.manage.
Persona access: Workspace Owner, Staff (role-based).
Headers
| Name | Value | Required |
|---|---|---|
| Authorization | Bearer WORKSPACE_TOKEN | Yes |
| Content-Type | application/json | Yes |
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| workspaceId | string | Yes | Workspace identifier |
| productId | string | Yes | Storefront product identifier |
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| generateImages | boolean | No | Generate a marketing image (default: false) |
| postsCount | number | No | Number of posts (1-3, default: 3) |
| useProductImages | boolean | No | Analyze product images with Vision API |
| imagePrompt | string | No | Advanced image prompt (overrides structured inputs) |
| adType | string | No | Ad type |
| tone | string | No | Writing tone |
| focusPoints | string | No | Key selling points |
| targetAudience | string | No | Target audience |
| imageType | string | No | post or story |
| artStyle | string | No | hero, negative_space, depth, lifestyle |
| mood | string | No | luxury, soft_feminine, modern, medical_clean |
| background | string | No | gradient, surface_backdrop, pastel, auto |
| productComposition | string | No | single_hero, grouped, side_layout |
| visualBoldness | string | No | low, medium, high |
Request Body
No body required.
Response 200 OK
{
"jobId": "65f50e1b6c6b9e2f1c0e61aa",
"status": "queued"
}
Notes
- Progress and completion are streamed via Socket.IO events:
post-generation:progressandpost-generation:completed. - Completion payload includes the generated posts, overlays, and
storefrontPostIds.
Common Errors
- 400 Bad Request: Invalid inputs (postsCount, price, currency, imageUrl)
- 401 Unauthorized: Missing/invalid auth token
- 403 Forbidden: Missing
store.products.managepermission - 404 Not Found: Workspace or product not found
- 422 Unprocessable Entity: Validation errors
- 500 Internal Server Error: Unexpected generation error