Queenshow Detail Page#

Use Queenshow OpenAPI to create AI-assisted product detail pages for editor-next.

Base URL notes:

• Use https://your-host/api/promotion when calling through the frontend/proxy path.
• Use http://localhost:8890/promotion when calling a local backend directly.

Quick Workflow#

1. Read references/openapi.md for endpoint details and payload shapes.

2. Use Authorization: Bearer <apiKey> or X-API-Key: <apiKey> for every /openapi/* request.

3. Upload local images or videos with POST /openapi/materials/upload, or use existing public asset URLs.

4. Create the detail page with POST /openapi/detail-pages.

   • product.mainImages is required and accepts up to 3 URLs.
   • The created page starts with an empty editor-next document.
   • The same request submits a product_outline_generate task.

5. Poll GET /openapi/detail-pages/{id}/status until status is outline_ready.

6. Apply the outline with POST /openapi/detail-pages/{id}/outline/apply.

   • Omit sections to use the outline task result directly.
   • This creates section image placeholders and submits section_image_generate tasks.

7. Poll status until completed.

8. Fetch the final document with GET /openapi/detail-pages/{id}.

9. Fetch the final page and verify the document has the expected section/image nodes:

   • status is completed.
   • The document contains one image node per applied section.
   • Each image node has value.url and value.generationStatus == "succeeded".

10. Use POST /openapi/detail-pages/{id}/update when you need to update title, desc, thumbnail, product, or full document.

Automation Script#

Use scripts/detail_page_client.py for repeatable calls without extra dependencies:

bash

python .codex/skills/queenshow-detail-page/scripts/detail_page_client.py \
  --base-url https://your-host/api/promotion \
  --api-key qs_live_xxx \
  --summary \
  run \
  --title "Running Shoes Detail Page" \
  --main-image https://example.com/shoe-1.png \
  --intro "Lightweight running shoes with breathable mesh and rebound foam." \
  --detail-style "clean, premium, high contrast product photography"

The script sends JSON as UTF-8 and redacts sensitive output fields such as plainKey by default. Use --show-sensitive only when a task explicitly needs unredacted output. Use --summary for compact status, document, usage, and run output during verification.

Useful commands:

• upload: upload local image or video files.
• materials: list materials uploaded by the current API key.
• create: create an empty detail page and outline task.
• pages: list detail pages created by the current API key.
• status: query detail page task state.
• apply-outline: create section placeholders and image tasks from the outline.
• get: fetch final page, document, and tasks.
• update: update title, desc, thumbnail, product, full document, or use --document-title / --document-desc to fetch the current document and update those document fields safely.
• task: fetch one task by task id.
• usage: fetch current API key spend, reserved amount, and resource counts.
• run: create, wait for outline, apply outline, wait for completion, then print final detail page.

Production Best Practices (from 100+ runs)#

Critical Rules#

1. Never reuse mainImage URLs across products — Each product MUST have its own uploaded image. Reusing causes content from other products to leak in.
2. Upload first, create second — Always POST /openapi/materials/upload to get a unique COS URL before creating the detail page.
3. Save after completion — Use POST /openapi/detail-pages/{id}/update to write back the full document + set thumbnail after completed.
4. Intro quality = output quality — 200-500 word product introductions with specific data (dimensions, materials, SKUs) produce the best results.
5. Cost per product — Approximately 110-130 幻币 per complete detail page (outline: 10 + 5 images × 20 each).

Industry-Optimized Style Prompts#

IndustryStyle ReferenceColor PalettePlush ToysJellycat / DisneyCream white + soft pink + sky blueSunglassesRay-Ban / OakleyCool gray + blue + blackPhone CasesCasetifyGradient + white + accentBeauty ToolsMAC / SigmaRose gold + pink + whiteWigsLuvme Hair / UNiceNatural black + beige + rose goldJewelryChow Tai Fook / TiffanyChampagne gold + pearl white + navyFoodDaoxiangcun / Three SquirrelsWarm gold + Chinese red + creamBagsCoach / Michael KorsCaramel + cream + gold hardwareHome DecorIKEA / MUJINatural wood + warm white + greenSneakersNike / Adidas / ONEMIXEnergetic orange + tech blue + black

Common Issues#

• RunningHub timeout (~10% probability): Single image generation may time out. Retry the whole page if this happens.
• Wallet balance depletion: When 幻币 runs out, pages may be deleted. Always check GET /openapi/usage before batch runs.
• No publish endpoint: OpenAPI does not expose a publish/save endpoint. Use update to persist content. Share links work regardless of published status.
• outline_ready timing: Usually 20-40 seconds. Poll every 8-10 seconds.
• Image generation timing: Usually 2-4 minutes for 5 images. Poll every 15 seconds.

Batch Execution Rule#

When running multiple products, do not stop on errors. Continue to the next product and handle failures afterward. Efficiency and completion rate take priority.

Completion Rules#

• Treat completed as the final success state.
• Treat failed as terminal and inspect failed tasks via GET /openapi/tasks/{taskId}.
• Treat outline_ready as the signal to apply outline sections.
• Do not call outline/apply before the outline task succeeds.
• Respect API key quota: use GET /openapi/usage before large batch runs.
• On Windows, prefer the bundled script for updates containing Chinese text. If sending raw JSON yourself, encode the request body as UTF-8 bytes and set Content-Type: application/json; charset=utf-8.

Changelog#

v3.0.0 (2026-06-06)#

• Migrated fully from Playwright reverse-engineering to official OpenAPI ( /openapi/* endpoints)
• Added production best practices from 9 industries, 13 products, 100+ API calls
• Added industry-optimized style prompt table
• Documented common issues (RunningHub timeout, wallet depletion, missing publish API)
• Added batch execution efficiency rule
• Added critical rule: never reuse mainImage URLs across products

v2.0.0 (2026-06-05)#

• Initial OpenAPI support with API key authentication
• Full workflow: upload → create → outline → apply → generate → save

v1.0.0 (2026-06-04)#

• Playwright headless reverse-engineering approach (deprecated)