{"openapi":"3.1.0","info":{"title":"聚好帧 Video API","version":"1.12.0","description":"Asynchronous H3 video generation. Choose outputResolution and outputFps when creating; 1080p/2k always generate native 768P then upscale; 60 fps adds interpolation. One job stays running until its final output is ready. Quotes include all fees, with a single charge and full refund on pipeline failure. Send outputKey from the quote to detect changes. Existing plans cover complete generation. qualityMode: fast=turbo, high=10 steps with turbo off, ultra=20 steps with turbo off. Fast forbids reference videos. Each mode uses its independently configured pricing.qualityMultipliers coefficient for output; reference input is billed separately. Legacy steps remain supported: public 10-20, active admin 10-50. Legacy 10 without video maps to fast; 10 with video maps to high; 20 maps to ultra; other values keep numeric routing and steps/10 billing. Omit both to retain legacy defaults. Explicit steps must match qualityMode when supplied together. Existing response fields remain available; jobs add qualityMode and quotes add qualityMode/qualityMultiplier. Query capabilities and an authenticated quote before submitting; credits are authoritative and currency amounts are display equivalents."},"servers":[{"url":"/api"}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"h3_live_..."}}},"security":[{"ApiKey":[]}],"paths":{"/videos/upload-policy":{"get":{"security":[],"summary":"Get current media upload policy","description":"Returns the live image, video, audio and combined upload limits. Call before uploading media.","responses":{"200":{"description":"Current upload limits","content":{"application/json":{"schema":{"type":"object","properties":{"uploadLimits":{"type":"object","properties":{"imageMaxBytes":{"type":"integer","minimum":1},"videoMaxBytes":{"type":"integer","minimum":1},"audioMaxBytes":{"type":"integer","minimum":1},"totalMaxBytes":{"type":"integer","minimum":1},"imageMaxCount":{"type":"integer","minimum":1},"videoMaxCount":{"type":"integer","minimum":1},"audioMaxCount":{"type":"integer","minimum":1},"videoMaxSeconds":{"type":"integer","minimum":1},"libraryMaxFiles":{"type":"integer","minimum":1}}}}}}}}}}},"/videos/capabilities":{"get":{"security":[],"summary":"List enabled profiles and generation modes","responses":{"200":{"description":"Capabilities, current immutable price version, public Step limit of 20, model service health and Ref2VA availability. Authenticated quotes return the account-specific Step limit."}}}},"/videos/quote":{"post":{"security":[{},{"ApiKey":[]}],"summary":"Calculate an authoritative quote","description":"Use the account API key for discounts and plan benefits. Send the same qualityMode and actual total reference-video seconds that will be used on submission. Fast rejects referenceVideoSeconds greater than zero. No charge or task is created.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"outputResolution":{"type":"string","enum":["576P","768P","1080p","2k"]},"outputFps":{"type":"string","enum":["original","60"],"default":"original"},"outputKey":{"type":"string","description":"Current quote outputKey"},"resolution":{"type":"string","enum":["576P","768P","1080p","2k"]},"duration":{"type":"integer","minimum":4,"maximum":15},"count":{"type":"integer","minimum":1,"maximum":8},"qualityMode":{"type":"string","enum":["fast","high","ultra"],"description":"fast=turbo (no reference videos), high=10 steps with turbo off, ultra=20 steps with turbo off. High and ultra support reference videos. Explicit steps must equal 10 for fast/high or 20 for ultra. Mode-specific coefficients are returned in pricing.qualityMultipliers."},"steps":{"type":"integer","minimum":10,"maximum":50,"description":"Legacy optional input. Public maximum 20; active admin maximum 50. Without qualityMode, 10/no-video maps to fast, 10/with-video maps to high, 20 maps to ultra, using the corresponding configured coefficient. Other values use steps/10 billing. Omitted defaults to 10 only when qualityMode is absent. Retained for backward compatibility."},"referenceVideoSeconds":{"type":"number","minimum":0,"maximum":48,"description":"Total measured reference video duration. Creation re-probes selected files."}}}}}},"responses":{"200":{"description":"Quote includes qualityMode, qualityMultiplier, legacy steps/stepMultiplier and current pricing.qualityMultipliers; fees, discounts and plan coverage are included."},"400":{"description":"INVALID_INPUT, INVALID_QUALITY_MODE, QUALITY_STEPS_CONFLICT or FAST_MODE_REFERENCE_VIDEO_NOT_SUPPORTED; no task/charge."}}}},"/videos":{"post":{"summary":"Create one or more asynchronous video jobs","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":191}}],"requestBody":{"required":true,"description":"Combined uploaded image, video and audio files are limited by the current upload policy; multipart/form-data byte overhead does not count toward the combined media limit. Files selected from the asset library also count toward the combined media limit.","content":{"multipart/form-data":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","maxLength":7000},"outputResolution":{"type":"string","enum":["576P","768P","1080p","2k"]},"outputFps":{"type":"string","enum":["original","60"],"default":"original"},"outputKey":{"type":"string","description":"Current quote outputKey"},"resolution":{"type":"string","enum":["576P","768P","1080p","2k"],"default":"576P"},"duration":{"type":"integer","minimum":4,"maximum":15,"default":5},"aspectRatio":{"type":"string","enum":["auto","16:9","1:1","9:16"],"default":"16:9"},"count":{"type":"integer","minimum":1,"maximum":8,"default":1,"description":"Number of videos to create with distinct seeds"},"qualityMode":{"type":"string","enum":["fast","high","ultra"],"description":"fast=turbo (no reference videos), high=10 steps with turbo off, ultra=20 steps with turbo off. High and ultra support reference videos. Explicit steps must equal 10 for fast/high or 20 for ultra. Mode-specific coefficients are returned in pricing.qualityMultipliers."},"steps":{"type":"integer","minimum":10,"maximum":50,"description":"Legacy optional input. Public maximum 20; active admin maximum 50. Without qualityMode, 10/no-video maps to fast, 10/with-video maps to high, 20 maps to ultra, using the corresponding configured coefficient. Other values use steps/10 billing. Omitted defaults to 10 only when qualityMode is absent. Retained for backward compatibility."},"mode":{"type":"string","enum":["auto","t2va","fl2va","ref2va"],"default":"auto","description":"auto infers the mode from uploaded fields. ref2va requires at least one referenceImages, referenceVideos or referenceAudios field and cannot be combined with keyframes."},"pricingVersionId":{"type":"string","format":"uuid","description":"Price version returned by capabilities or quote. A stale version is rejected with PRICE_CHANGED."},"pricingKey":{"type":"string","description":"Return the pricingKey from a quote when submitting. A daily time-period boundary or schedule change returns PRICE_CHANGED; request a new quote. Daily base prices use Asia/Shanghai and promotions multiply the applicable base price."},"discountRate":{"type":"number","minimum":0,"maximum":1,"description":"Immutable billingDiscountRate returned by an authenticated quote. It is validated against the account and cannot grant a discount."},"seed":{"type":"integer","minimum":0,"maximum":4294967295},"projectId":{"type":"string","format":"uuid"},"startFrame":{"type":"string","format":"binary","description":"First-frame PNG, JPEG or WebP file, at most 10 MiB. Uploading this field selects fl2va when mode is auto."},"endFrame":{"type":"string","format":"binary","description":"Optional last-frame PNG, JPEG or WebP file, at most 10 MiB. Requires startFrame and cannot be used alone."},"referenceImages":{"type":"array","minItems":1,"maxItems":9,"description":"Reference PNG, JPEG or WebP files. Repeat the exact referenceImages field name in upload order; each file is at most 10 MiB.","items":{"type":"string","format":"binary"}},"referenceVideos":{"type":"array","minItems":1,"maxItems":3,"description":"Only high/ultra support reference videos (legacy steps remain compatible). Reference MP4 or MOV files, each at most 10 MiB and 16 seconds.","items":{"type":"string","format":"binary"}},"referenceVideoAssetIds":{"type":"string","description":"JSON array of owned video asset UUIDs. Fast mode forbids nonempty video references. Combined upload and library limits apply."},"referenceAudios":{"type":"array","minItems":1,"maxItems":3,"description":"Reference WAV, MP3 or M4A files, each at most 10 MiB.","items":{"type":"string","format":"binary"}}}},"encoding":{"startFrame":{"contentType":"image/png, image/jpeg, image/webp"},"endFrame":{"contentType":"image/png, image/jpeg, image/webp"},"referenceImages":{"style":"form","explode":true,"contentType":"application/octet-stream"},"referenceVideos":{"style":"form","explode":true,"contentType":"application/octet-stream"},"referenceVideoAssetIds":{"type":"string","description":"JSON array of owned video asset UUIDs. Fast mode forbids nonempty video references. Combined upload and library limits apply."},"referenceAudios":{"style":"form","explode":true,"contentType":"application/octet-stream"}}}}},"responses":{"202":{"description":"Jobs accepted by the platform; scheduled jobs have statusSource=platform, queueWaitSeconds and submissionNotBefore without an upstreamTaskId. Response includes job, jobs, batchId and immutable quote snapshot"},"400":{"description":"Invalid mode/file combination, missing reference media, QUALITY_STEPS_CONFLICT, or FAST_MODE_REFERENCE_VIDEO_NOT_SUPPORTED"},"402":{"description":"Insufficient credits; no jobs are created"},"409":{"description":"Concurrent-job limit exceeded or PRICE_CHANGED; refresh the quote"},"413":{"description":"A per-file or combined media limit from the current upload policy was exceeded"},"422":{"description":"Profile is not enabled"},"503":{"description":"Model service, Ref2VA or pricing unavailable"}}},"get":{"summary":"List jobs with page, status, projectId and search filters","responses":{"200":{"description":"Paginated job list"}}}},"/videos/{id}":{"get":{"summary":"Get a video job","description":"Platform-scheduled jobs expose queued with statusSource=platform and submissionNotBefore; after upstream acceptance, queued/running/progress come from H3.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Job details including qualityMode (null for other legacy steps), steps, stepMultiplier, statusSource, upstreamTaskId and progressAvailable"}}}},"/videos/{id}/content":{"get":{"summary":"Download a completed MP4","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"MP4 video"}}}}}}