Skip to content

fix: align Platform and Growth Studio clients with the official API docs - #4

Merged
scoutfield merged 3 commits into
mainfrom
fix/api-doc-alignment
Oct 11, 2026
Merged

scoutfield merged 3 commits into
mainfrom
fix/api-doc-alignment

Conversation

@scoutfield

Copy link
Copy Markdown
Owner

A review of every operation against docs.platform.pixverse.ai and the
Growth Studio OpenAPI integration guide found the fusion img_id bug was
systemic, plus several other request-shape and recovery mismatches.

Platform requests

  • Serialize every field the API reference types as integer (img_id,
    img_ids, template_id, source_video_id, video_media_id, audio_media_id,
    keyframe_id, restyle_id, agent_id, nested reference IDs) as lossless
    JSON numbers via a per-operation map. ~17 billable operations sent
    quoted IDs that the API rejects with ErrCode 400013.
  • Send template_ids as one comma-separated query value and type upload
    file parts by extension instead of application/octet-stream.

Platform validation

  • sound-effect: drop the nonexistent prompt field; use the documented
    sound_effect_content and original_sound_switch.
  • music-mv: accept vibe_mv_v3/vibe_mv_v3_custom, make aspect_ratio and
    quality optional, fix mv_style/music_style lists, link the public doc.
  • template prompt may be empty; transition accepts only
    first_frame_img/last_frame_img; viral-recreation references require
    uploaded IDs and strip local paths; documented bounds for
    multi-transition durations, keyframe_id, restyle seed, extend models,
    avatar TTS length, real-estate pro-only fields, v6 omni video-only
    fusion.

Platform polling and webhooks

  • Keep polling through transient read errors (transport, 429, 5xx,
    ErrCode 500069/500044) until the timeout; default interval 5s and
    timeout 30m; fresh Ai-trace-id per read retry. Billable submissions
    are still sent exactly once.
  • Answer verified duplicate webhooks with 200 ok, dedupe on
    (id, status), accept null values, sort keys by code point, and make
    the timestamp tolerance configurable (default 6h to cover retries).

Growth Studio

  • Use the documented /openapi/v1/folders endpoints and send
    video.folder_id instead of a top-level folder_id.
  • Retry GET requests on 429/503 honoring Retry-After; never retry
    create, edit, upload, or folder create.
  • Parse responses losslessly, keep request_id in error.json, keep
    user folder names unchanged, and validate documented create, edit,
    list, and upload limits.

Co-Authored-By: Claude Opus 5.5 noreply@anthropic.com

scoutfield and others added 3 commits October 10, 2026 19:30
A review of every operation against docs.platform.pixverse.ai and the
Growth Studio OpenAPI integration guide found the fusion img_id bug was
systemic, plus several other request-shape and recovery mismatches.

Platform requests
- Serialize every field the API reference types as integer (img_id,
  img_ids, template_id, source_video_id, video_media_id, audio_media_id,
  keyframe_id, restyle_id, agent_id, nested reference IDs) as lossless
  JSON numbers via a per-operation map. ~17 billable operations sent
  quoted IDs that the API rejects with ErrCode 400013.
- Send template_ids as one comma-separated query value and type upload
  file parts by extension instead of application/octet-stream.

Platform validation
- sound-effect: drop the nonexistent prompt field; use the documented
  sound_effect_content and original_sound_switch.
- music-mv: accept vibe_mv_v3/vibe_mv_v3_custom, make aspect_ratio and
  quality optional, fix mv_style/music_style lists, link the public doc.
- template prompt may be empty; transition accepts only
  first_frame_img/last_frame_img; viral-recreation references require
  uploaded IDs and strip local paths; documented bounds for
  multi-transition durations, keyframe_id, restyle seed, extend models,
  avatar TTS length, real-estate pro-only fields, v6 omni video-only
  fusion.

Platform polling and webhooks
- Keep polling through transient read errors (transport, 429, 5xx,
  ErrCode 500069/500044) until the timeout; default interval 5s and
  timeout 30m; fresh Ai-trace-id per read retry. Billable submissions
  are still sent exactly once.
- Answer verified duplicate webhooks with 200 ok, dedupe on
  (id, status), accept null values, sort keys by code point, and make
  the timestamp tolerance configurable (default 6h to cover retries).

Growth Studio
- Use the documented /openapi/v1/folders endpoints and send
  video.folder_id instead of a top-level folder_id.
- Retry GET requests on 429/503 honoring Retry-After; never retry
  create, edit, upload, or folder create.
- Parse responses losslessly, keep request_id in error.json, keep
  user folder names unchanged, and validate documented create, edit,
  list, and upload limits.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s as integers

Live API checks showed both schemas are wrong: quoted IDs in fusion
video_references[] and image.template img_ids[] are rejected with
ErrCode 400013, while integers are accepted, matching the v6 video
reference and image template guide examples.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scoutfield
scoutfield merged commit cccd203 into main Oct 11, 2026
2 checks passed
@scoutfield
scoutfield deleted the fix/api-doc-alignment branch October 11, 2026 04:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant