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 \x3CapiKey> or X-API-Key: \x3CapiKey> 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:

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

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)