Align Platform and Growth Studio clients with the official API docs

[scoutfield]

Summary

A full review of the kit against docs.platform.pixverse.ai and the Growth Studio OpenAPI integration guide found that the fusion img_id bug (983538b) was one case of a wider problem, along with other request-shape and recovery mismatches. This PR fixes them all.

Platform requests

• Integer IDs: ~17 billable operations sent integer-typed IDs as JSON strings, which the API rejects with ErrCode 400013. A per-operation map in src/platform/request.js now serializes every documented integer field losslessly. Fields the docs type as string (mask_id(s), lip_sync_tts_speaker_id, webhook_id) stay quoted.
• template_ids is sent as one comma-separated query value.
• Upload file parts are typed by extension instead of application/octet-stream.

Platform validation

• video.sound-effect no longer requires a prompt field the API doesn't have; it uses sound_effect_content.
• agent.music-mv:
  • accepts vibe_mv_v3 and vibe_mv_v3_custom
  • aspect_ratio and quality are optional
  • corrected mv_style and music_style lists
  • links to the public VibeMV doc
• video.template allows an empty prompt.
• video.transition accepts only first_frame_img and last_frame_img.
• Viral-recreation references must carry uploaded IDs; local paths are stripped before sending.
• Documented bounds are now enforced for:
  • multi-transition durations
  • keyframe_id (minimum 1)
  • restyle seed
  • extend models
  • avatar TTS length
  • real-estate pro-only fields
  • v6 omni video-only fusion

Platform polling and webhooks

• Polling: keeps going through transient read errors (transport, 429, 5xx, ErrCode 500069/500044) until the timeout. The default interval is now 5s and the default timeout 30m. Each read retry gets a fresh Ai-trace-id. Billable submissions are still sent exactly once.
• Webhooks:
  • a verified duplicate gets 200 ok instead of 409
  • deliveries are deduplicated on (id, status)
  • null values are accepted
  • keys are sorted by code point
  • timestamp tolerance is configurable, with a 6h default so it covers PixVerse's retry schedule

Growth Studio

• Uses the documented GET/POST /openapi/v1/folders instead of /marketing_hub/folder/*, and removes the separate folder key and prefix settings.
• Sends video.folder_id instead of a top-level folder_id.
• Retries GET requests on 429/5xx, honoring Retry-After. Create, edit, upload and folder create are never retried.
• Parses responses losslessly and keeps request_id in error.json.
• Sends user folder names unchanged.
• Validates the documented create, edit, list and upload limits.

Not changed or needs confirmation

• Doc conflicts settled by live calls: fusion video_references IDs and image.template img_ids are listed as string in the schemas, but the API rejects quoted values (400013), so both are now sent as integers. Upscale integers were confirmed too.
• Image templates: every type=2 template returned by the template list is a "workflow template" that the API says belongs to an undocumented POST /openapi/v2/template/generate; image.template could not complete live.
• Not in the public guide: the Growth Studio PDP (/openapi/v1/ecommerce_pdp/video) and wallet endpoints. Left unchanged; worth confirming with PixVerse.
• Not enforced locally: per-model duration and aspect-ratio rules for older models.

Test plan

• npm test: 490/490
• npm run test:customer-plugin: 40/40
• npm run check, npm run security:scan
• Request fixtures now expect integer IDs, and the contract tests compare bodies with a lossless parser
• Live Platform run: 16 billable operations succeeded with integer IDs (227 credits); quoted IDs confirmed rejected with 400013, and agents/voice checked free via typed-but-invalid requests
• Live Growth Studio reads: folders list on /openapi/v1/folders, avatars, video list, wallet
• Live Growth Studio video.folder_id: a nonexistent folder at video.folder_id returns 404 FOLDER_NOT_FOUND, while the same folder at the old top-level folder_id is ignored and a video is created. So the old placement silently dropped the folder.
• Live Growth Studio generic POST /openapi/v1/videos success: every attempt (with or without a folder) returns 500 INTERNAL_ERROR and leaves a failed video with GENERATION_FAILED, uncharged. This looks server-side and needs PixVerse.

🤖 Generated with Claude Code