openapi: 3.1.0 info: title: Beatra API version: 0.1.0 paths: /v1/models: get: tags: - catalog summary: List models (OpenAI-compatible) description: Returns OpenAI-compatible model objects available to the caller. operationId: list_models_openai_compat_v1_models_get parameters: - name: Authorization in: header required: true schema: type: string description: Bearer API key. - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/OpenAIModelList' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/catalog/models: get: tags: - catalog summary: List catalog models description: Returns the same model list as `/v1/models`, namespaced under the Beatra catalog. operationId: list_catalog_models_v1_catalog_models_get parameters: - name: Authorization in: header required: true schema: type: string description: Bearer API key. - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/OpenAIModelList' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/catalog/capabilities: get: tags: - catalog summary: List capabilities operationId: list_capabilities_v1_catalog_capabilities_get parameters: - name: Authorization in: header required: true schema: type: string description: Bearer API key. - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CapabilityList' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/catalog/capabilities/{capability}: get: tags: - catalog summary: Capability detail with typed media interface cards operationId: get_capability_v1_catalog_capabilities__capability__get parameters: - name: capability in: path required: true schema: type: string title: Capability - name: Authorization in: header required: true schema: type: string description: Bearer API key. - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/CapabilityDetail' - $ref: '#/components/schemas/VideoCapabilityDetail' - $ref: '#/components/schemas/MusicCapabilityDetail' - $ref: '#/components/schemas/AudioCapabilityDetail' title: Response Get Capability V1 Catalog Capabilities Capability Get headers: X-Request-Id: description: Request id for support correlation. schema: type: string '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/catalog/models/{model}: get: tags: - catalog summary: Model detail with typed media interface cards operationId: get_model_v1_catalog_models__model__get parameters: - name: model in: path required: true schema: type: string title: Model - name: Authorization in: header required: true schema: type: string description: Bearer API key. - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/ModelDetail' - $ref: '#/components/schemas/VideoModelDetail' - $ref: '#/components/schemas/MusicModelDetail' - $ref: '#/components/schemas/AudioModelDetail' title: Response Get Model V1 Catalog Models Model Get headers: X-Request-Id: description: Request id for support correlation. schema: type: string '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/images/generations: post: tags: - images summary: Generate one to four images from text description: Create an asynchronous image-generation task without source images. `auto` selects a live model that can satisfy the complete request; a concrete model is validated exactly as requested and is never substituted. operationId: images_generations_v1_images_generations_post parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 title: Idempotency-Key - name: Authorization in: header required: true schema: type: string description: Bearer API key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TextToImageRequest' responses: '202': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/images/image-to-image: post: tags: - images summary: Transform one to four ordered reference images description: Create an asynchronous task that uses one to four ordered images as references for a new result. `auto` selects a compatible live model; incompatible concrete-model requests are rejected without dropping references or changing controls. operationId: images_i2i_v1_images_image_to_image_post parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 title: Idempotency-Key - name: Authorization in: header required: true schema: type: string description: Bearer API key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ImageToImageRequest' responses: '202': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/images/edits: post: tags: - images summary: Edit a base image with optional references and regions description: Create an asynchronous edit task where `images[0]` is the base image and later images are ordered references. Optional normalized regions target inputs by index. `auto` selects a compatible live model; a concrete model is never substituted. operationId: images_edits_v1_images_edits_post parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 title: Idempotency-Key - name: Authorization in: header required: true schema: type: string description: Bearer API key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ImageEditRequest' responses: '202': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/videos/text-to-video: post: tags: - videos summary: Generate video from text without source media description: Create an asynchronous video task from a text prompt, with optional driving audio for compatible models. The selected model must support every explicit control. operationId: videos_t2v_v1_videos_text_to_video_post parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 title: Idempotency-Key - name: Authorization in: header required: true schema: type: string description: Bearer API key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TextToVideoRequest' responses: '202': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/videos/image-to-video: post: tags: - videos summary: Animate one strict opening image description: Create an asynchronous video task whose input image is the required first frame, not a loose visual reference. The selected model must support every explicit control. operationId: videos_i2v_v1_videos_image_to_video_post parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 title: Idempotency-Key - name: Authorization in: header required: true schema: type: string description: Bearer API key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ImageToVideoRequest' responses: '202': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/videos/reference-to-video: post: tags: - videos summary: Generate video from ordered multimodal references description: Create an asynchronous video task from ordered image, video, and audio references. Reference kinds, counts, durations, and controls are validated against the selected model. operationId: videos_r2v_v1_videos_reference_to_video_post parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 title: Idempotency-Key - name: Authorization in: header required: true schema: type: string description: Bearer API key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReferenceToVideoRequest' responses: '202': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/videos/frames-to-video: post: tags: - videos summary: Generate video between strict first and last images description: Create an asynchronous video task constrained by required first-frame and last-frame images. Use image-to-video when only the opening frame must be fixed. operationId: videos_f2v_v1_videos_frames_to_video_post parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 title: Idempotency-Key - name: Authorization in: header required: true schema: type: string description: Bearer API key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FramesToVideoRequest' responses: '202': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/videos/edit: post: tags: - videos summary: Edit one source video with optional multimodal references description: Create an asynchronous instruction-based edit of one source video. Optional ordered image, video, and audio references are accepted when the selected model supports them. operationId: videos_edit_v1_videos_edit_post parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 title: Idempotency-Key - name: Authorization in: header required: true schema: type: string description: Bearer API key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VideoEditRequest' responses: '202': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/videos/extend: post: tags: - videos summary: Extend one source video before or after its current content description: Create an asynchronous continuation immediately before or after one source video. `duration` is required and always means the final returned-video duration; it must exceed the trusted source duration. operationId: videos_extend_v1_videos_extend_post parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 title: Idempotency-Key - name: Authorization in: header required: true schema: type: string description: Bearer API key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VideoExtendRequest' responses: '202': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/music/text-to-music: post: tags: - music summary: Generate music from a prompt and/or lyrics operationId: text_to_music_v1_music_text_to_music_post parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 title: Idempotency-Key - name: Authorization in: header required: true schema: type: string description: Bearer API key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TextToMusicRequest' responses: '202': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/music/reference-audio-to-music: post: tags: - music summary: Generate music from a reference audio operationId: ref_audio_to_music_v1_music_reference_audio_to_music_post parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 title: Idempotency-Key - name: Authorization in: header required: true schema: type: string description: Bearer API key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReferenceAudioToMusicRequest' responses: '202': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/audio/speech: post: tags: - audio summary: Text-to-speech operationId: text_to_speech_v1_audio_speech_post parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 title: Idempotency-Key - name: Authorization in: header required: true schema: type: string description: Bearer API key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TextToSpeechRequest' responses: '202': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '404': description: Voice not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': description: Invalid request or voice/model mismatch content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/voices: get: tags: - voices summary: List available voices operationId: list_voices_v1_voices_get parameters: - name: language in: query required: false schema: anyOf: - type: string - type: 'null' description: BCP-47 / ISO-639-1 filter title: Language description: BCP-47 / ISO-639-1 filter - name: gender in: query required: false schema: anyOf: - type: string - type: 'null' title: Gender - name: category in: query required: false schema: anyOf: - type: string - type: 'null' description: preset | cloned title: Category description: preset | cloned - name: q in: query required: false schema: anyOf: - type: string - type: 'null' description: Search in display names title: Q description: Search in display names - name: Authorization in: header required: true schema: type: string description: Bearer API key. - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/VoiceList' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string post: tags: - voices summary: Clone a voice from an audio sample operationId: clone_voice_v1_voices_post parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 title: Idempotency-Key - name: Authorization in: header required: true schema: type: string description: Bearer API key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VoiceCloneRequest' responses: '202': description: Clone task accepted; task output carries the new voice_id content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/voices/{voice_id}: get: tags: - voices summary: Get a voice's detail operationId: get_voice_v1_voices__voice_id__get parameters: - name: voice_id in: path required: true schema: type: string title: Voice Id - name: Authorization in: header required: true schema: type: string description: Bearer API key. - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Voice' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string delete: tags: - voices summary: Delete a cloned voice operationId: delete_voice_v1_voices__voice_id__delete parameters: - name: voice_id in: path required: true schema: type: string title: Voice Id - name: Authorization in: header required: true schema: type: string description: Bearer API key. - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. responses: '204': description: Successful Response headers: X-Request-Id: description: Request id for support correlation. schema: type: string '404': description: Not found, or not a cloned voice you own content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/uploads: post: tags: - uploads summary: "Single-shot upload (\u2264100MB)" operationId: upload_v1_uploads_post parameters: - name: Authorization in: header required: true schema: type: string description: Bearer API key. - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. requestBody: required: true content: multipart/form-data: schema: $ref: '#/components/schemas/Body_upload_v1_uploads_post' responses: '201': description: Upload accepted; artifact created content: application/json: schema: $ref: '#/components/schemas/UploadResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '200': description: Content already exists; returns existing artifact headers: X-Request-Id: description: Request id for support correlation. schema: type: string '413': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Request Entity Too Large headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/tasks: get: tags: - tasks summary: List the caller's tasks description: Returns TaskSummary by default. Use `?expand=output,usage,billing,callback,input` or `?expand=all` to return full TaskEnvelope items. operationId: list_tasks_v1_tasks_get parameters: - name: status in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Status - name: capability in: query required: false schema: anyOf: - type: array items: type: string - type: 'null' title: Capability - name: created_after in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' title: Created After - name: created_before in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' title: Created Before - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 20 title: Limit - name: cursor in: query required: false schema: anyOf: - type: string - type: 'null' title: Cursor - name: order in: query required: false schema: enum: - asc - desc type: string default: desc title: Order - name: expand in: query required: false schema: anyOf: - type: string - type: 'null' description: 'Comma-separated fields to include: output,usage,billing,callback,input,all' title: Expand description: 'Comma-separated fields to include: output,usage,billing,callback,input,all' - name: Authorization in: header required: true schema: type: string description: Bearer API key. - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/app__api__v1__schemas__tasks__TaskListResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/tasks/{task_id}: get: tags: - tasks summary: Get a task by id operationId: get_task_v1_tasks__task_id__get parameters: - name: task_id in: path required: true schema: type: string title: Task Id - name: Authorization in: header required: true schema: type: string description: Bearer API key. - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/tasks/{task_id}/cancel: post: tags: - tasks summary: Cancel a task operationId: cancel_task_v1_tasks__task_id__cancel_post parameters: - name: task_id in: path required: true schema: type: string title: Task Id - name: Authorization in: header required: true schema: type: string description: Bearer API key. - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/TaskCancelRequest' - type: 'null' title: Req responses: '200': description: Already terminal; returns final state (idempotent) content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '409': description: Remote execution cannot be confirmed canceled; task continues content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found headers: X-Request-Id: description: Request id for support correlation. schema: type: string '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: X-Request-Id: description: Request id for support correlation. schema: type: string /v1/health: get: tags: - health summary: Health description: "Cheap self-check \u2014 does NOT depend on external stores." operationId: health_v1_health_get responses: '200': description: Successful Response content: application/json: schema: additionalProperties: true type: object title: Response Health V1 Health Get headers: X-Request-Id: description: Request id for support correlation. schema: type: string parameters: - name: X-Request-Id in: header required: false schema: type: string description: Optional client request id echoed in the response. components: schemas: AudioAutoSelectionCard: properties: request_dependent: type: boolean title: Request Dependent selection_inputs: items: type: string const: voice type: array title: Selection Inputs default_for_omitted_request: anyOf: - type: string - type: 'null' title: Default For Omitted Request candidate_order: items: type: string type: array title: Candidate Order persisted_selection_field: type: string const: resolved_model title: Persisted Selection Field default: resolved_model additionalProperties: false type: object required: - request_dependent - selection_inputs - default_for_omitted_request - candidate_order title: AudioAutoSelectionCard AudioCapabilityDetail: properties: capability: type: string enum: - text_to_speech - voice_clone title: Capability endpoint: type: string title: Endpoint input_modality: type: string title: Input Modality output_modality: type: string enum: - audio - voice title: Output Modality execution_mode: type: string const: async title: Execution Mode default: async description: type: string title: Description status: type: string enum: - available - unavailable title: Status auto: $ref: '#/components/schemas/AudioAutoSelectionCard' models: items: $ref: '#/components/schemas/AudioModelCard' type: array title: Models additionalProperties: false type: object required: - capability - endpoint - input_modality - output_modality - description - status - auto - models title: AudioCapabilityDetail AudioIntegerRange: properties: minimum: type: integer title: Minimum maximum: type: integer title: Maximum additionalProperties: false type: object required: - minimum - maximum title: AudioIntegerRange AudioModelCard: properties: schema_version: type: string const: audio-interface.v1 title: Schema Version default: audio-interface.v1 model: type: string title: Model display_name: type: string title: Display Name owned_by: type: string const: Beatra title: Owned By default: Beatra capability: type: string enum: - text_to_speech - voice_clone title: Capability status: type: string const: available title: Status default: available controls: items: type: string type: array title: Controls constraints: anyOf: - $ref: '#/components/schemas/SpeechConstraintsCard' - $ref: '#/components/schemas/VoiceCloneConstraintsCard' title: Constraints pricing: $ref: '#/components/schemas/AudioPricingCard' additionalProperties: false type: object required: - model - display_name - capability - controls - constraints - pricing title: AudioModelCard AudioModelDetail: properties: model: type: string title: Model display_name: type: string title: Display Name owned_by: type: string const: Beatra title: Owned By default: Beatra description: type: string title: Description status: type: string enum: - available - unavailable title: Status interfaces: items: $ref: '#/components/schemas/AudioModelCard' type: array title: Interfaces additionalProperties: false type: object required: - model - display_name - description - status - interfaces title: AudioModelDetail AudioNumberRange: properties: minimum: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Minimum maximum: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Maximum exclusive_minimum: type: boolean title: Exclusive Minimum default: false additionalProperties: false type: object required: - minimum - maximum title: AudioNumberRange AudioPricingCard: properties: meter: type: string enum: - character - task title: Meter unit: type: string enum: - character - task title: Unit unit_price_credits: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Unit Price Credits scale: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Scale billing_basis: type: string enum: - beatra_weighted_characters - successful_activated_voice title: Billing Basis estimate_formula: type: string const: (unit_price_credits * billable_quantity) / scale title: Estimate Formula default: (unit_price_credits * billable_quantity) / scale additionalProperties: false type: object required: - meter - unit - unit_price_credits - scale - billing_basis title: AudioPricingCard Body_upload_v1_uploads_post: properties: file: type: string contentMediaType: application/octet-stream title: File purpose: type: string enum: - media_input - reference_audio - voice_clone_source title: Purpose default: media_input media_type: anyOf: - type: string enum: - image - video - audio - type: 'null' title: Media Type metadata: anyOf: - type: string - type: 'null' title: Metadata type: object required: - file title: Body_upload_v1_uploads_post CapabilityDetail: properties: capability: type: string enum: - text_to_image - image_to_image - image_edit title: Capability endpoint: type: string title: Endpoint input_modality: type: string title: Input Modality output_modality: type: string const: image title: Output Modality default: image execution_mode: type: string const: async title: Execution Mode default: async description: type: string title: Description status: type: string enum: - available - unavailable title: Status default: available auto: $ref: '#/components/schemas/ImageAutoSelectionCard' models: items: anyOf: - $ref: '#/components/schemas/ImageInterfaceCard' - $ref: '#/components/schemas/ImageModelSummaryCard' type: array title: Models max_output_images: anyOf: - type: integer maximum: 4.0 minimum: 1.0 - type: 'null' title: Max Output Images max_canvas_pixels: anyOf: - type: integer exclusiveMinimum: 0.0 - type: 'null' title: Max Canvas Pixels starting_credits: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Starting Credits additionalProperties: false type: object required: - capability - endpoint - input_modality - description - auto - models title: CapabilityDetail CapabilityList: properties: object: type: string const: list title: Object default: list data: items: $ref: '#/components/schemas/CapabilityListItem' type: array title: Data type: object required: - data title: CapabilityList CapabilityListItem: properties: capability: type: string title: Capability endpoint: type: string title: Endpoint input_modality: type: string title: Input Modality output_modality: type: string title: Output Modality execution_mode: type: string title: Execution Mode description: anyOf: - type: string - type: 'null' title: Description model_count: type: integer title: Model Count type: object required: - capability - endpoint - input_modality - output_modality - execution_mode - model_count title: CapabilityListItem ErrorBody: properties: code: type: string title: Code description: Stable public error code type: type: string title: Type description: Broad SDK-friendly error family message: type: string title: Message description: Human-readable explanation retryable: type: boolean title: Retryable description: If true, retrying the exact same request may succeed details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: Code-specific structured info request_id: type: string title: Request Id description: Echo of X-Request-Id for support correlation param: anyOf: - type: string - type: 'null' title: Param description: JSON Pointer to offending field, if applicable type: object required: - code - type - message - retryable - request_id title: ErrorBody ErrorResponse: properties: error: $ref: '#/components/schemas/ErrorBody' type: object required: - error title: ErrorResponse FramesToVideoRequest: properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: "Caller-supplied metadata; \u226416 keys, key \u226464 chars,\ \ value \u2264512 chars" callback_url: anyOf: - type: string maxLength: 2048 pattern: ^https:// - type: 'null' title: Callback Url description: HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state callback_signing_key_id: anyOf: - type: string maxLength: 64 minLength: 1 pattern: ^whkey_[A-Za-z0-9]+$ - type: 'null' title: Callback Signing Key Id description: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided. model: type: string enum: - auto - minimax-h3 - wan2.7-i2v - seedance-2 - seedance-2-fast - seedance-2-mini title: Model description: Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. default: auto negative_prompt: anyOf: - type: string maxLength: 500 - type: 'null' title: Negative Prompt description: Content or qualities to avoid when supported by the selected model. duration: anyOf: - type: integer - type: string const: auto - type: 'null' title: Duration description: Requested output duration as integer seconds, or 'auto' when the selected model may choose its documented duration. Omit to use the selected model default. aspect_ratio: anyOf: - type: string enum: - '16:9' - '9:16' - '1:1' - '4:3' - '3:4' - '4:5' - '5:4' - '21:9' - '9:21' - adaptive - type: 'null' title: Aspect Ratio description: Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. resolution: anyOf: - type: string enum: - 480p - 720p - 1080p - 2k - 4k - type: 'null' title: Resolution description: Requested output short-edge tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. seed: anyOf: - type: integer maximum: 2147483647.0 minimum: 0.0 - type: 'null' title: Seed enhance_prompt: anyOf: - type: boolean - type: 'null' title: Enhance Prompt description: Ask the selected model to improve the prompt before generation. watermark: anyOf: - type: boolean - type: 'null' title: Watermark description: Whether generated video should include the model watermark. generate_audio: anyOf: - type: boolean - type: 'null' title: Generate Audio description: Whether the selected model should generate synchronized audio. web_search: anyOf: - type: boolean - type: 'null' title: Web Search description: Whether the selected model may use web search during generation. return_last_frame: anyOf: - type: boolean - type: 'null' title: Return Last Frame description: Whether to return the generated video's last frame as an image artifact. prompt: anyOf: - type: string maxLength: 7000 - type: 'null' title: Prompt description: Optional instructions for the motion between the two strict boundary frames. first_frame: oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/MediaInputDataUri' title: First Frame description: Required image that must be the video's first frame. discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/MediaInputDataUri' url: '#/components/schemas/MediaInputUrl' last_frame: oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/MediaInputDataUri' title: Last Frame description: Required image that must be the video's last frame. discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/MediaInputDataUri' url: '#/components/schemas/MediaInputUrl' driving_audio: anyOf: - oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/MediaInputDataUri' discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/MediaInputDataUri' url: '#/components/schemas/MediaInputUrl' - type: 'null' title: Driving Audio description: Optional driving audio. Supplying it requires a model that supports this control. additionalProperties: false type: object required: - first_frame - last_frame title: FramesToVideoRequest ImageAspectRange: properties: minimum: type: string title: Minimum maximum: type: string title: Maximum additionalProperties: false type: object required: - minimum - maximum title: ImageAspectRange ImageAutoSelectionCard: properties: default_model: type: string const: auto title: Default Model default: auto basic_request_preference: type: string title: Basic Request Preference request_dependent: type: boolean const: true title: Request Dependent default: true persisted_selection_field: type: string const: resolved_model title: Persisted Selection Field default: resolved_model description: type: string title: Description additionalProperties: false type: object required: - basic_request_preference - description title: ImageAutoSelectionCard ImageCanvasCard: properties: default: additionalProperties: type: string type: object title: Default preset_tiers: items: type: string enum: - 1K - 2K - 4K type: array title: Preset Tiers target: $ref: '#/components/schemas/ImageTargetCanvasCard' source_aspect_anchor: type: string enum: - none - first_input - last_input title: Source Aspect Anchor additionalProperties: false type: object required: - default - preset_tiers - target - source_aspect_anchor title: ImageCanvasCard ImageControlCard: properties: field: type: string title: Field value_type: type: string enum: - string - integer - boolean - enum - canvas - image_collection - palette - region_collection title: Value Type required: type: boolean title: Required nullable: type: boolean title: Nullable default: anyOf: - type: string - type: integer - type: boolean - additionalProperties: type: string type: object - type: 'null' title: Default model_default: anyOf: - type: boolean - type: 'null' title: Model Default omitted_behavior: type: string enum: - invalid - use_public_default - use_model_default - same_as_omitted - random title: Omitted Behavior null_behavior: type: string enum: - invalid - same_as_omitted - use_model_default title: Null Behavior allowed_values: anyOf: - items: type: string type: array - type: 'null' title: Allowed Values minimum: anyOf: - type: integer - type: number - type: 'null' title: Minimum maximum: anyOf: - type: integer - type: number - type: 'null' title: Maximum min_items: anyOf: - type: integer - type: 'null' title: Min Items max_items: anyOf: - type: integer - type: 'null' title: Max Items max_length: anyOf: - type: integer - type: 'null' title: Max Length additionalProperties: false type: object required: - field - value_type - required - nullable - default - omitted_behavior - null_behavior title: ImageControlCard description: One public request field and its stable omission/null semantics. ImageEditPresetCanvas: properties: type: type: string const: preset title: Type tier: $ref: '#/components/schemas/ImageResolution' aspect: anyOf: - type: string pattern: ^(?:source|[1-9][0-9]{0,5}:[1-9][0-9]{0,5})(?![\s\S]) - type: 'null' title: Aspect description: Positive width:height ratio with integer components from 1 to 999999, or `source` to inherit the first input image's ratio. Positive ratios are normalized by greatest common divisor. default: source additionalProperties: false type: object required: - type - tier title: ImageEditPresetCanvas description: Edit canvas whose ratio may be inherited from the first input image. ImageEditRegion: properties: image_index: type: integer minimum: 0.0 title: Image Index x: type: number exclusiveMaximum: 1.0 minimum: 0.0 title: X y: type: number exclusiveMaximum: 1.0 minimum: 0.0 title: Y width: type: number maximum: 1.0 exclusiveMinimum: 0.0 title: Width height: type: number maximum: 1.0 exclusiveMinimum: 0.0 title: Height additionalProperties: false type: object required: - image_index - x - y - width - height title: ImageEditRegion description: Normalized rectangle associated with one ordered input image. ImageEditRequest: properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: "Caller-supplied metadata; \u226416 keys, key \u226464 chars,\ \ value \u2264512 chars" callback_url: anyOf: - type: string maxLength: 2048 pattern: ^https:// - type: 'null' title: Callback Url description: HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state callback_signing_key_id: anyOf: - type: string maxLength: 64 minLength: 1 pattern: ^whkey_[A-Za-z0-9]+$ - type: 'null' title: Callback Signing Key Id description: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided. model: type: string enum: - auto - gpt-image-2 - image-01 - image-01-live - wan2.7-image-pro - wan2.7-image - qwen-image-2.0-pro - qwen-image-2.0 title: Model description: Use auto for compatibility-based selection from the configured live candidates. A concrete model is evaluated exactly as requested and is never substituted. default: auto prompt: type: string minLength: 1 pattern: \S title: Prompt description: Required prompt containing at least one non-whitespace character. count: type: integer maximum: 4.0 minimum: 1.0 title: Count description: Requested output image count. The public range is one through four, and the selected model must support the exact count; Beatra does not split the request. default: 1 canvas: oneOf: - $ref: '#/components/schemas/ImageEditPresetCanvas' - $ref: '#/components/schemas/ImageTargetCanvas' title: Canvas description: Desired output canvas. The default is a 2K tier derived from the first base image's ratio; actual output dimensions remain authoritative. default: type: preset tier: 2K aspect: source discriminator: propertyName: type mapping: preset: '#/components/schemas/ImageEditPresetCanvas' target: '#/components/schemas/ImageTargetCanvas' seed: anyOf: - type: integer maximum: 2147483647.0 minimum: 0.0 - type: 'null' title: Seed description: Optional random seed. Supplying it constrains model eligibility; omit it for model-managed randomness. negative_prompt: anyOf: - type: string - type: 'null' title: Negative Prompt description: Optional content or qualities to avoid. Supplying it constrains model eligibility and is rejected when no compatible model is available. enhance_prompt: anyOf: - type: boolean - type: 'null' title: Enhance Prompt description: Omit or use null to retain the selected model's documented default; an explicit boolean constrains model eligibility. palette: anyOf: - items: $ref: '#/components/schemas/ImagePaletteColor' type: array maxItems: 10 minItems: 3 - type: 'null' title: Palette description: Three to ten weighted RGB colors. Runtime validation requires the weights to sum exactly to 1.0000. images: items: oneOf: - $ref: '#/components/schemas/ImageMediaInputUrl' - $ref: '#/components/schemas/ImageMediaInputArtifact' - $ref: '#/components/schemas/ImageMediaInputDataUri' discriminator: propertyName: type mapping: artifact: '#/components/schemas/ImageMediaInputArtifact' data_uri: '#/components/schemas/ImageMediaInputDataUri' url: '#/components/schemas/ImageMediaInputUrl' type: array maxItems: 4 minItems: 1 title: Images description: Ordered inputs; images[0] is the base and later entries are references. edit_regions: anyOf: - items: $ref: '#/components/schemas/ImageEditRegion' type: array maxItems: 8 minItems: 1 - type: 'null' title: Edit Regions description: Flat normalized rectangles keyed by an input image_index. Runtime validation enforces cross-coordinate and collection relations. additionalProperties: false type: object required: - prompt - images title: ImageEditRequest description: Edit a base image with optional ordered references and normalized regions. ImageInputHardConstraints: properties: max_bytes: anyOf: - type: integer - type: 'null' title: Max Bytes edge_pixels: anyOf: - $ref: '#/components/schemas/ImageIntegerRange' - type: 'null' aspect_ratio: anyOf: - $ref: '#/components/schemas/ImageAspectRange' - type: 'null' alpha: type: string enum: - allowed - reject_png_alpha title: Alpha additionalProperties: false type: object required: - max_bytes - edge_pixels - aspect_ratio - alpha title: ImageInputHardConstraints ImageInputRecommendations: properties: edge_pixels: anyOf: - $ref: '#/components/schemas/ImageIntegerRange' - type: 'null' additionalProperties: false type: object required: - edge_pixels title: ImageInputRecommendations ImageInputTransportCard: properties: accepted_kinds: items: type: string enum: - artifact - data_uri - https_url type: array title: Accepted Kinds https_only: type: boolean title: Https Only data_uri_max_encoded_length: anyOf: - type: integer - type: 'null' title: Data Uri Max Encoded Length additionalProperties: false type: object required: - accepted_kinds - https_only - data_uri_max_encoded_length title: ImageInputTransportCard ImageInputsCard: properties: minimum_count: type: integer minimum: 0.0 title: Minimum Count public_max_count: type: integer maximum: 4.0 minimum: 0.0 title: Public Max Count native_max_count: type: integer minimum: 0.0 title: Native Max Count formats: items: type: string type: array title: Formats hard_constraints: $ref: '#/components/schemas/ImageInputHardConstraints' recommendations: $ref: '#/components/schemas/ImageInputRecommendations' animation: additionalProperties: type: string enum: - as_provided - first_frame type: object title: Animation transport: $ref: '#/components/schemas/ImageInputTransportCard' ordering: type: string enum: - none - ordered_references - first_is_base_remaining_are_references title: Ordering source_aspect_anchor: type: string enum: - none - first_input - last_input title: Source Aspect Anchor additionalProperties: false type: object required: - minimum_count - public_max_count - native_max_count - formats - hard_constraints - recommendations - animation - transport - ordering - source_aspect_anchor title: ImageInputsCard ImageIntegerRange: properties: minimum: type: integer title: Minimum maximum: type: integer title: Maximum additionalProperties: false type: object required: - minimum - maximum title: ImageIntegerRange ImageInterfaceCard: properties: schema_version: type: string const: image-interface.v1 title: Schema Version default: image-interface.v1 model: type: string title: Model display_name: type: string title: Display Name owned_by: type: string const: Beatra title: Owned By default: Beatra capability: type: string enum: - text_to_image - image_to_image - image_edit title: Capability quality_tier: type: string enum: - pro - fast title: Quality Tier status: type: string const: available title: Status default: available controls: items: $ref: '#/components/schemas/ImageControlCard' type: array title: Controls prompt: $ref: '#/components/schemas/ImagePromptCard' inputs: $ref: '#/components/schemas/ImageInputsCard' outputs: $ref: '#/components/schemas/ImageOutputsCard' canvas: $ref: '#/components/schemas/ImageCanvasCard' rules: items: $ref: '#/components/schemas/ImageInterfaceRule' type: array title: Rules pricing: $ref: '#/components/schemas/ImagePricingCard' auto: $ref: '#/components/schemas/ImageAutoSelectionCard' additionalProperties: false type: object required: - model - display_name - capability - quality_tier - controls - prompt - inputs - outputs - canvas - rules - pricing - auto title: ImageInterfaceCard description: Canonical image discovery record shared by REST, MCP and Console. ImageInterfaceRule: properties: id: type: string title: Id when: items: $ref: '#/components/schemas/ImageRulePredicate' type: array title: When effect: $ref: '#/components/schemas/ImageRuleEffect' additionalProperties: false type: object required: - id - when - effect title: ImageInterfaceRule ImageMediaInputArtifact: properties: type: type: string const: artifact title: Type artifact_id: type: string title: Artifact Id additionalProperties: false type: object required: - type - artifact_id title: ImageMediaInputArtifact description: Closed reference to a Beatra artifact. ImageMediaInputDataUri: properties: type: type: string const: data_uri title: Type data: type: string maxLength: 262144 title: Data description: Data URI with a 256 KiB encoded inline transport cap. This is not the model image-byte limit; use an artifact or public HTTPS URL for larger inputs. additionalProperties: false type: object required: - type - data title: ImageMediaInputDataUri description: Closed inline image reference accepted by Beatra. ImageMediaInputUrl: properties: type: type: string const: url title: Type url: type: string pattern: ^[Hh][Tt][Tt][Pp][Ss]://(?:(?=[A-Za-z0-9.-]{1,253}\.?(?=[:/?#]|$))(?=[A-Za-z0-9.-]*[A-Za-z])[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*\.?|(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])|\[(?:(?:[0-9A-Fa-f]{1,4}:){6}(?:[0-9A-Fa-f]{1,4}:[0-9A-Fa-f]{1,4}|(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))|::(?:[0-9A-Fa-f]{1,4}:){5}(?:[0-9A-Fa-f]{1,4}:[0-9A-Fa-f]{1,4}|(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))|(?:[0-9A-Fa-f]{1,4})?::(?:[0-9A-Fa-f]{1,4}:){4}(?:[0-9A-Fa-f]{1,4}:[0-9A-Fa-f]{1,4}|(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))|(?:(?:[0-9A-Fa-f]{1,4}:){0,1}[0-9A-Fa-f]{1,4})?::(?:[0-9A-Fa-f]{1,4}:){3}(?:[0-9A-Fa-f]{1,4}:[0-9A-Fa-f]{1,4}|(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))|(?:(?:[0-9A-Fa-f]{1,4}:){0,2}[0-9A-Fa-f]{1,4})?::(?:[0-9A-Fa-f]{1,4}:){2}(?:[0-9A-Fa-f]{1,4}:[0-9A-Fa-f]{1,4}|(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))|(?:(?:[0-9A-Fa-f]{1,4}:){0,3}[0-9A-Fa-f]{1,4})?::[0-9A-Fa-f]{1,4}:(?:[0-9A-Fa-f]{1,4}:[0-9A-Fa-f]{1,4}|(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))|(?:(?:[0-9A-Fa-f]{1,4}:){0,4}[0-9A-Fa-f]{1,4})?::(?:[0-9A-Fa-f]{1,4}:[0-9A-Fa-f]{1,4}|(?:(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9]{2}|[1-9]?[0-9]))|(?:(?:[0-9A-Fa-f]{1,4}:){0,5}[0-9A-Fa-f]{1,4})?::[0-9A-Fa-f]{1,4}|(?:(?:[0-9A-Fa-f]{1,4}:){0,6}[0-9A-Fa-f]{1,4})?::)\])(?::0*(?:[1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?(?:[/?#][^\s]*)?(?![\s\S]) title: Url description: Public HTTPS image URL with a non-empty host. additionalProperties: false type: object required: - type - url title: ImageMediaInputUrl description: Closed HTTPS image reference accepted by Beatra. ImageModelPricingOption: properties: meter: type: string const: image_count title: Meter default: image_count unit: type: string const: image title: Unit default: image unit_price_credits: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Unit Price Credits scale: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Scale resolution: anyOf: - type: string - type: 'null' title: Resolution billing_basis: type: string const: successful_image_count title: Billing Basis default: successful_image_count estimate_formula: type: string const: (unit_price_credits * billable_quantity) / scale title: Estimate Formula default: (unit_price_credits * billable_quantity) / scale additionalProperties: false type: object required: - unit_price_credits - scale title: ImageModelPricingOption description: Beatra price option retained for existing image models. ImageModelSummaryCard: properties: id: type: string title: Id capabilities: items: type: string enum: - text_to_image - image_to_image - image_edit type: array title: Capabilities supported_controls: items: type: string type: array title: Supported Controls constraints: additionalProperties: true type: object title: Constraints pricing: items: $ref: '#/components/schemas/ImageModelPricingOption' type: array minItems: 1 title: Pricing additionalProperties: false type: object required: - id - capabilities - pricing title: ImageModelSummaryCard description: 'Existing image model projection alongside typed image-interface cards. The four PH-72 models use :class:`ImageInterfaceCard`. Existing image models keep their established generic discovery shape so adding an implementation or model family cannot silently remove previously selectable products.' ImageOutputRelationship: type: string enum: - independent - sequence title: ImageOutputRelationship ImageOutputsCard: properties: public_max_count: type: integer maximum: 4.0 minimum: 1.0 title: Public Max Count native_max_independent_count: type: integer minimum: 1.0 title: Native Max Independent Count native_max_sequence_count: anyOf: - type: integer minimum: 1.0 - type: 'null' title: Native Max Sequence Count relationships: items: type: string enum: - independent - sequence type: array title: Relationships format: type: string const: image/png title: Format default: image/png additionalProperties: false type: object required: - public_max_count - native_max_independent_count - relationships title: ImageOutputsCard ImagePaletteColor: properties: color: type: string pattern: ^#[0-9A-Fa-f]{6}(?![\s\S]) title: Color weight: anyOf: - type: number maximum: 1.0 exclusiveMinimum: 0.0 - type: string pattern: ^\+?(?:0*\.(?=[0-9]{0,3}[1-9])[0-9]{1,4}|0*1(?:\.0{0,4})?)(?![\s\S]) title: Weight description: Exact decimal weight greater than 0 and at most 1, with no more than 4 fractional digits. Decimal strings avoid binary-float ambiguity. additionalProperties: false type: object required: - color - weight title: ImagePaletteColor description: One exact weighted RGB color in a requested palette. ImagePresetCanvas: properties: type: type: string const: preset title: Type tier: $ref: '#/components/schemas/ImageResolution' aspect: anyOf: - type: string pattern: ^[1-9][0-9]{0,5}:[1-9][0-9]{0,5}(?![\s\S]) - type: 'null' title: Aspect description: Positive width:height ratio whose components are integers from 1 to 999999, normalized by greatest common divisor. A tier describes quality, not exact pixels. default: '16:9' additionalProperties: false type: object required: - type - tier title: ImagePresetCanvas description: Named canvas tier with an optional positive aspect ratio. ImagePricingCard: properties: unit_credits: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Unit Credits unit: type: string const: image title: Unit default: image billing_basis: type: string const: successful_image_count title: Billing Basis default: successful_image_count additionalProperties: false type: object required: - unit_credits title: ImagePricingCard ImagePromptCard: properties: limit: type: integer exclusiveMinimum: 0.0 title: Limit unit: type: string enum: - characters - qwen_tokens title: Unit overflow: type: string const: reject title: Overflow default: reject languages: items: type: string enum: - en - zh type: array title: Languages counter: type: string enum: - unicode_characters - qwen_open_family_proxy title: Counter counter_is_exact: type: boolean title: Counter Is Exact counter_unavailable_behavior: type: string const: reject title: Counter Unavailable Behavior default: reject additionalProperties: false type: object required: - limit - unit - languages - counter - counter_is_exact title: ImagePromptCard ImageResolution: type: string enum: - 1K - 2K - 4K title: ImageResolution description: Named quality tier, not a promise of exact encoded dimensions. ImageRuleEffect: properties: type: type: string enum: - allow - forbid - limit - require title: Type field: type: string title: Field value: anyOf: - type: string - type: integer - type: boolean - items: type: string type: array - type: 'null' title: Value additionalProperties: false type: object required: - type - field title: ImageRuleEffect ImageRulePredicate: properties: field: type: string title: Field operator: type: string enum: - equals - present - greater_than title: Operator value: anyOf: - type: string - type: integer - type: boolean - items: type: string type: array - type: 'null' title: Value additionalProperties: false type: object required: - field - operator title: ImageRulePredicate ImageTargetCanvas: properties: type: type: string const: target title: Type width: type: integer maximum: 999999.0 exclusiveMinimum: 0.0 title: Width description: Desired output width in pixels height: type: integer maximum: 999999.0 exclusiveMinimum: 0.0 title: Height description: Desired output height in pixels additionalProperties: false type: object required: - type - width - height title: ImageTargetCanvas description: Desired pixel target; the selected implementation may normalize actual output. ImageTargetCanvasCard: properties: supported: type: boolean title: Supported minimum_total_pixels: type: integer title: Minimum Total Pixels maximum_total_pixels: type: integer title: Maximum Total Pixels minimum_aspect_ratio: anyOf: - type: string - type: 'null' title: Minimum Aspect Ratio maximum_aspect_ratio: anyOf: - type: string - type: 'null' title: Maximum Aspect Ratio normalization_multiple: anyOf: - type: integer - type: 'null' title: Normalization Multiple actual_dimensions_may_differ: type: boolean title: Actual Dimensions May Differ additionalProperties: false type: object required: - supported - minimum_total_pixels - maximum_total_pixels - minimum_aspect_ratio - maximum_aspect_ratio - normalization_multiple - actual_dimensions_may_differ title: ImageTargetCanvasCard ImageToImageRequest: properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: "Caller-supplied metadata; \u226416 keys, key \u226464 chars,\ \ value \u2264512 chars" callback_url: anyOf: - type: string maxLength: 2048 pattern: ^https:// - type: 'null' title: Callback Url description: HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state callback_signing_key_id: anyOf: - type: string maxLength: 64 minLength: 1 pattern: ^whkey_[A-Za-z0-9]+$ - type: 'null' title: Callback Signing Key Id description: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided. model: type: string enum: - auto - gpt-image-2 - image-01 - image-01-live - wan2.7-image-pro - wan2.7-image - qwen-image-2.0-pro - qwen-image-2.0 title: Model description: Use auto for compatibility-based selection from the configured live candidates. A concrete model is evaluated exactly as requested and is never substituted. default: auto prompt: type: string minLength: 1 pattern: \S title: Prompt description: Required prompt containing at least one non-whitespace character. count: type: integer maximum: 4.0 minimum: 1.0 title: Count description: Requested output image count. The public range is one through four, and the selected model must support the exact count; Beatra does not split the request. default: 1 canvas: oneOf: - $ref: '#/components/schemas/ImageTransformPresetCanvas' - $ref: '#/components/schemas/ImageTargetCanvas' title: Canvas description: Desired output canvas. Preset `source` inherits the last input image's ratio; the omitted default is 2K at 16:9. default: type: preset tier: 2K aspect: '16:9' discriminator: propertyName: type mapping: preset: '#/components/schemas/ImageTransformPresetCanvas' target: '#/components/schemas/ImageTargetCanvas' seed: anyOf: - type: integer maximum: 2147483647.0 minimum: 0.0 - type: 'null' title: Seed description: Optional random seed. Supplying it constrains model eligibility; omit it for model-managed randomness. negative_prompt: anyOf: - type: string - type: 'null' title: Negative Prompt description: Optional content or qualities to avoid. Supplying it constrains model eligibility and is rejected when no compatible model is available. enhance_prompt: anyOf: - type: boolean - type: 'null' title: Enhance Prompt description: Omit or use null to retain the selected model's documented default; an explicit boolean constrains model eligibility. palette: anyOf: - items: $ref: '#/components/schemas/ImagePaletteColor' type: array maxItems: 10 minItems: 3 - type: 'null' title: Palette description: Three to ten weighted RGB colors. Runtime validation requires the weights to sum exactly to 1.0000. images: items: oneOf: - $ref: '#/components/schemas/ImageMediaInputUrl' - $ref: '#/components/schemas/ImageMediaInputArtifact' - $ref: '#/components/schemas/ImageMediaInputDataUri' discriminator: propertyName: type mapping: artifact: '#/components/schemas/ImageMediaInputArtifact' data_uri: '#/components/schemas/ImageMediaInputDataUri' url: '#/components/schemas/ImageMediaInputUrl' type: array maxItems: 4 minItems: 1 title: Images description: Ordered artifact, HTTPS URL, or data URI references. output_relationship: $ref: '#/components/schemas/ImageOutputRelationship' description: Use independent for unrelated results, or sequence for a related image set. An explicit value constrains model eligibility and is rejected when unsupported. default: independent additionalProperties: false type: object required: - prompt - images title: ImageToImageRequest description: Transform one to four ordered image references with a prompt. ImageToVideoRequest: properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: "Caller-supplied metadata; \u226416 keys, key \u226464 chars,\ \ value \u2264512 chars" callback_url: anyOf: - type: string maxLength: 2048 pattern: ^https:// - type: 'null' title: Callback Url description: HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state callback_signing_key_id: anyOf: - type: string maxLength: 64 minLength: 1 pattern: ^whkey_[A-Za-z0-9]+$ - type: 'null' title: Callback Signing Key Id description: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided. model: type: string enum: - auto - minimax-h3 - happyhorse-1.1-i2v - wan2.7-i2v - seedance-2 - seedance-2-fast - seedance-2-mini title: Model description: Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. default: auto negative_prompt: anyOf: - type: string maxLength: 500 - type: 'null' title: Negative Prompt description: Content or qualities to avoid when supported by the selected model. duration: anyOf: - type: integer - type: string const: auto - type: 'null' title: Duration description: Requested output duration as integer seconds, or 'auto' when the selected model may choose its documented duration. Omit to use the selected model default. aspect_ratio: anyOf: - type: string enum: - '16:9' - '9:16' - '1:1' - '4:3' - '3:4' - '4:5' - '5:4' - '21:9' - '9:21' - adaptive - type: 'null' title: Aspect Ratio description: Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. resolution: anyOf: - type: string enum: - 480p - 720p - 1080p - 2k - 4k - type: 'null' title: Resolution description: Requested output short-edge tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. seed: anyOf: - type: integer maximum: 2147483647.0 minimum: 0.0 - type: 'null' title: Seed enhance_prompt: anyOf: - type: boolean - type: 'null' title: Enhance Prompt description: Ask the selected model to improve the prompt before generation. watermark: anyOf: - type: boolean - type: 'null' title: Watermark description: Whether generated video should include the model watermark. generate_audio: anyOf: - type: boolean - type: 'null' title: Generate Audio description: Whether the selected model should generate synchronized audio. web_search: anyOf: - type: boolean - type: 'null' title: Web Search description: Whether the selected model may use web search during generation. return_last_frame: anyOf: - type: boolean - type: 'null' title: Return Last Frame description: Whether to return the generated video's last frame as an image artifact. prompt: anyOf: - type: string maxLength: 7000 - type: 'null' title: Prompt description: Optional motion, scene, and camera instructions for animating the opening image. image: oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/MediaInputDataUri' title: Image description: Required strict first-frame image; this is not a loose visual reference. discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/MediaInputDataUri' url: '#/components/schemas/MediaInputUrl' driving_audio: anyOf: - oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/MediaInputDataUri' discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/MediaInputDataUri' url: '#/components/schemas/MediaInputUrl' - type: 'null' title: Driving Audio description: Optional driving audio. Supplying it requires a model that supports this control. additionalProperties: false type: object required: - image title: ImageToVideoRequest ImageTransformPresetCanvas: properties: type: type: string const: preset title: Type tier: $ref: '#/components/schemas/ImageResolution' aspect: anyOf: - type: string pattern: ^(?:source|[1-9][0-9]{0,5}:[1-9][0-9]{0,5})(?![\s\S]) - type: 'null' title: Aspect description: Positive width:height ratio with integer components from 1 to 999999, or `source` to inherit the last input image's ratio. Positive ratios are normalized by greatest common divisor. default: '16:9' additionalProperties: false type: object required: - type - tier title: ImageTransformPresetCanvas description: Transform canvas whose ratio may be inherited from the last input image. MediaInputArtifact: properties: type: type: string const: artifact title: Type artifact_id: type: string title: Artifact Id description: ULID of a previously-uploaded artifact type: object required: - type - artifact_id title: MediaInputArtifact MediaInputDataUri: properties: type: type: string const: data_uri title: Type data: type: string maxLength: 262144 title: Data description: "Data URI (e.g. data:image/png;base64,...) \u2014 max 256KB\ \ encoded" type: object required: - type - data title: MediaInputDataUri MediaInputUrl: properties: type: type: string const: url title: Type url: type: string title: Url description: HTTPS URL. External URLs are downloaded and re-hosted to Beatra CDN. type: object required: - type - url title: MediaInputUrl MiniMaxMusicAudioSetting: properties: sample_rate: anyOf: - type: integer enum: - 16000 - 24000 - 32000 - 44100 - type: 'null' title: Sample Rate bitrate: anyOf: - type: integer enum: - 32000 - 64000 - 128000 - 256000 - type: 'null' title: Bitrate format: anyOf: - type: string const: mp3 - type: 'null' title: Format additionalProperties: false type: object title: MiniMaxMusicAudioSetting MiniMaxMusicOptions: properties: lyrics_optimizer: anyOf: - type: boolean - type: 'null' title: Lyrics Optimizer aigc_watermark: anyOf: - type: boolean - type: 'null' title: Aigc Watermark audio_setting: anyOf: - $ref: '#/components/schemas/MiniMaxMusicAudioSetting' - type: 'null' additionalProperties: false type: object title: MiniMaxMusicOptions ModelDetail: properties: model: type: string title: Model display_name: type: string title: Display Name owned_by: type: string const: Beatra title: Owned By default: Beatra description: type: string title: Description status: type: string enum: - available - unavailable title: Status default: available interfaces: items: anyOf: - $ref: '#/components/schemas/ImageInterfaceCard' - $ref: '#/components/schemas/ImageModelSummaryCard' type: array title: Interfaces additionalProperties: false type: object required: - model - display_name - description - interfaces title: ModelDetail MusicAutoSelectionCard: properties: request_dependent: type: boolean const: false title: Request Dependent default: false default_for_omitted_request: anyOf: - type: string - type: 'null' title: Default For Omitted Request candidate_order: items: type: string type: array title: Candidate Order persisted_selection_field: type: string const: resolved_model title: Persisted Selection Field default: resolved_model additionalProperties: false type: object required: - default_for_omitted_request - candidate_order title: MusicAutoSelectionCard MusicCapabilityDetail: properties: capability: type: string enum: - text_to_music - reference_audio_to_music title: Capability endpoint: type: string title: Endpoint input_modality: type: string title: Input Modality output_modality: type: string const: audio title: Output Modality default: audio execution_mode: type: string const: async title: Execution Mode default: async description: type: string title: Description status: type: string enum: - available - unavailable title: Status auto: $ref: '#/components/schemas/MusicAutoSelectionCard' models: items: $ref: '#/components/schemas/MusicModelCard' type: array title: Models additionalProperties: false type: object required: - capability - endpoint - input_modality - description - status - auto - models title: MusicCapabilityDetail MusicConstraintsCard: properties: prompt_min_characters: type: integer minimum: 1.0 title: Prompt Min Characters prompt_max_characters: type: integer minimum: 1.0 title: Prompt Max Characters custom_prompt_max_characters: anyOf: - type: integer minimum: 1.0 - type: 'null' title: Custom Prompt Max Characters lyrics_min_characters: type: integer minimum: 1.0 title: Lyrics Min Characters lyrics_max_characters: type: integer minimum: 1.0 title: Lyrics Max Characters title_max_characters: type: integer minimum: 1.0 title: Title Max Characters instrumental_forbids_lyrics: type: boolean const: true title: Instrumental Forbids Lyrics default: true vocal_lyrics_requirement: type: string enum: - required_or_optimizer - required_in_custom_mode - reference_audio_asr_or_supplied title: Vocal Lyrics Requirement reference_audio: anyOf: - $ref: '#/components/schemas/MusicReferenceAudioConstraints' - type: 'null' additionalProperties: false type: object required: - prompt_min_characters - prompt_max_characters - lyrics_min_characters - lyrics_max_characters - title_max_characters - vocal_lyrics_requirement title: MusicConstraintsCard MusicModelCard: properties: schema_version: type: string const: music-interface.v1 title: Schema Version default: music-interface.v1 model: type: string title: Model display_name: type: string title: Display Name owned_by: type: string const: Beatra title: Owned By default: Beatra capability: type: string enum: - text_to_music - reference_audio_to_music title: Capability status: type: string const: available title: Status default: available controls: items: type: string type: array title: Controls constraints: $ref: '#/components/schemas/MusicConstraintsCard' output_mime_type: type: string const: audio/mpeg title: Output Mime Type default: audio/mpeg output_cardinality: type: string const: one_or_more_clips title: Output Cardinality default: one_or_more_clips pricing: $ref: '#/components/schemas/MusicPricingCard' additionalProperties: false type: object required: - model - display_name - capability - controls - constraints - pricing title: MusicModelCard MusicModelDetail: properties: model: type: string title: Model display_name: type: string title: Display Name owned_by: type: string const: Beatra title: Owned By default: Beatra description: type: string title: Description status: type: string enum: - available - unavailable title: Status interfaces: items: $ref: '#/components/schemas/MusicModelCard' type: array title: Interfaces additionalProperties: false type: object required: - model - display_name - description - status - interfaces title: MusicModelDetail MusicModelOptions: properties: suno: anyOf: - $ref: '#/components/schemas/SunoMusicOptions' - type: 'null' minimax: anyOf: - $ref: '#/components/schemas/MiniMaxMusicOptions' - type: 'null' additionalProperties: false type: object title: MusicModelOptions description: Model-family scoped public options for music generation. MusicPricingCard: properties: unit_credits: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Unit Credits unit: type: string const: task title: Unit default: task billing_basis: type: string const: successful_task title: Billing Basis default: successful_task additionalProperties: false type: object required: - unit_credits title: MusicPricingCard MusicReferenceAudioConstraints: properties: required: type: boolean const: true title: Required default: true minimum_seconds: anyOf: - type: integer minimum: 1.0 - type: 'null' title: Minimum Seconds maximum_seconds: type: integer minimum: 1.0 title: Maximum Seconds maximum_bytes: anyOf: - type: integer exclusiveMinimum: 0.0 - type: 'null' title: Maximum Bytes mime_types: items: type: string type: array minItems: 1 title: Mime Types accepted_kinds: items: type: string enum: - artifact - data_uri - https_url type: array title: Accepted Kinds additionalProperties: false type: object required: - maximum_seconds - mime_types - accepted_kinds title: MusicReferenceAudioConstraints OpenAIModel: properties: id: type: string title: Id object: type: string const: model title: Object default: model created: type: integer title: Created description: Unix seconds owned_by: type: string const: Beatra title: Owned By default: Beatra type: object required: - id - created title: OpenAIModel OpenAIModelList: properties: object: type: string const: list title: Object default: list data: items: $ref: '#/components/schemas/OpenAIModel' type: array title: Data type: object required: - data title: OpenAIModelList ReferenceAudioToMusicRequest: properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: Caller-supplied metadata; limited by task creation policy. callback_url: anyOf: - type: string maxLength: 2048 pattern: ^https:// - type: 'null' title: Callback Url description: HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state callback_signing_key_id: anyOf: - type: string maxLength: 64 minLength: 1 pattern: ^whkey_[A-Za-z0-9]+$ - type: 'null' title: Callback Signing Key Id description: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided. model: type: string enum: - auto - minimax-music-3.0 - suno-5.5 title: Model prompt: type: string maxLength: 2000 minLength: 1 title: Prompt description: Music concept, style, mood, genre, or instrumentation prompt. lyrics: anyOf: - type: string maxLength: 5000 - type: 'null' title: Lyrics description: Optional lyrics text. Must be omitted for instrumental music. instrumental: type: boolean title: Instrumental description: When true, generate instrumental music without vocals. default: false title: anyOf: - type: string maxLength: 100 - type: 'null' title: Title model_options: anyOf: - $ref: '#/components/schemas/MusicModelOptions' - type: 'null' description: Options grouped by public music model family. reference_audio: oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/MediaInputDataUri' title: Reference Audio discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/MediaInputDataUri' url: '#/components/schemas/MediaInputUrl' additionalProperties: false type: object required: - model - prompt - reference_audio title: ReferenceAudioToMusicRequest description: Generate music from a prompt, optional lyrics, and reference audio. ReferenceToVideoRequest: properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: "Caller-supplied metadata; \u226416 keys, key \u226464 chars,\ \ value \u2264512 chars" callback_url: anyOf: - type: string maxLength: 2048 pattern: ^https:// - type: 'null' title: Callback Url description: HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state callback_signing_key_id: anyOf: - type: string maxLength: 64 minLength: 1 pattern: ^whkey_[A-Za-z0-9]+$ - type: 'null' title: Callback Signing Key Id description: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided. model: type: string enum: - auto - minimax-h3 - happyhorse-1.1-r2v - wan2.7-r2v - seedance-2 - seedance-2-fast - seedance-2-mini title: Model description: Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. default: auto negative_prompt: anyOf: - type: string maxLength: 500 - type: 'null' title: Negative Prompt description: Content or qualities to avoid when supported by the selected model. duration: anyOf: - type: integer - type: string const: auto - type: 'null' title: Duration description: Requested output duration as integer seconds, or 'auto' when the selected model may choose its documented duration. Omit to use the selected model default. aspect_ratio: anyOf: - type: string enum: - '16:9' - '9:16' - '1:1' - '4:3' - '3:4' - '4:5' - '5:4' - '21:9' - '9:21' - adaptive - type: 'null' title: Aspect Ratio description: Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. resolution: anyOf: - type: string enum: - 480p - 720p - 1080p - 2k - 4k - type: 'null' title: Resolution description: Requested output short-edge tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. seed: anyOf: - type: integer maximum: 2147483647.0 minimum: 0.0 - type: 'null' title: Seed enhance_prompt: anyOf: - type: boolean - type: 'null' title: Enhance Prompt description: Ask the selected model to improve the prompt before generation. watermark: anyOf: - type: boolean - type: 'null' title: Watermark description: Whether generated video should include the model watermark. generate_audio: anyOf: - type: boolean - type: 'null' title: Generate Audio description: Whether the selected model should generate synchronized audio. web_search: anyOf: - type: boolean - type: 'null' title: Web Search description: Whether the selected model may use web search during generation. return_last_frame: anyOf: - type: boolean - type: 'null' title: Return Last Frame description: Whether to return the generated video's last frame as an image artifact. prompt: anyOf: - type: string maxLength: 7000 - type: 'null' title: Prompt description: Optional instructions describing how the ordered references should guide the output. references: items: $ref: '#/components/schemas/VideoReference' type: array maxItems: 15 minItems: 1 title: References description: One to fifteen ordered image, video, or audio references. Model-specific kind, count, duration, and combination limits still apply. additionalProperties: false type: object required: - references title: ReferenceToVideoRequest SpeechCharacterWeights: properties: han_ideograph: type: integer const: 2 title: Han Ideograph default: 2 other: type: integer const: 1 title: Other default: 1 additionalProperties: false type: object title: SpeechCharacterWeights SpeechConstraintsCard: properties: input_max_characters: type: integer const: 50000 title: Input Max Characters default: 50000 supported_languages: items: type: string type: array title: Supported Languages formats: items: type: string enum: - mp3 - wav - flac - opus - pcm type: array title: Formats sample_rates: items: type: integer enum: - 8000 - 16000 - 22050 - 24000 - 32000 - 44100 type: array title: Sample Rates speed: $ref: '#/components/schemas/AudioNumberRange' volume: $ref: '#/components/schemas/AudioNumberRange' pitch: $ref: '#/components/schemas/AudioIntegerRange' emotions: items: type: string type: array title: Emotions billing_character_weights: $ref: '#/components/schemas/SpeechCharacterWeights' minimum_billable_characters: type: integer const: 0 title: Minimum Billable Characters default: 0 additionalProperties: false type: object required: - supported_languages - formats - sample_rates - speed - volume - pitch - emotions title: SpeechConstraintsCard SunoMusicOptions: properties: custom_mode: anyOf: - type: boolean - type: 'null' title: Custom Mode negative_tags: anyOf: - type: string maxLength: 1000 - type: 'null' title: Negative Tags vocal_gender: anyOf: - type: string enum: - m - f - type: 'null' title: Vocal Gender style_weight: anyOf: - type: number multipleOf: 0.01 maximum: 1.0 minimum: 0.0 - type: 'null' title: Style Weight weirdness_constraint: anyOf: - type: number multipleOf: 0.01 maximum: 1.0 minimum: 0.0 - type: 'null' title: Weirdness Constraint audio_weight: anyOf: - type: number multipleOf: 0.01 maximum: 1.0 minimum: 0.0 - type: 'null' title: Audio Weight persona_id: anyOf: - type: string maxLength: 128 minLength: 1 - type: 'null' title: Persona Id persona_model: anyOf: - type: string maxLength: 64 minLength: 1 - type: 'null' title: Persona Model additionalProperties: false type: object title: SunoMusicOptions TaskBilling: properties: charged_credits: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Charged Credits description: Credits charged to wallet for this Task. Populated by PR-2/3. refunded_credits: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Refunded Credits description: Credits refunded for this Task. Populated by PR-3. net_charged_credits: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Net Charged Credits description: 'Final customer charge: charged_credits minus refunded_credits.' type: object title: TaskBilling TaskCallback: properties: url: type: string title: Url status: type: string enum: - pending - dispatching - delivered - retrying - failed title: Status attempt_count: type: integer title: Attempt Count delivered_at: anyOf: - type: string format: date-time - type: 'null' title: Delivered At last_error: anyOf: - type: string - type: 'null' title: Last Error description: "Last HTTP body/error (\u2264512 chars, truncated)" type: object required: - url - status - attempt_count title: TaskCallback TaskCancelRequest: properties: reason: anyOf: - type: string maxLength: 512 - type: 'null' title: Reason type: object title: TaskCancelRequest TaskEnvelope: properties: object: type: string const: task title: Object default: task task_id: type: string title: Task Id status: type: string enum: - queued - running - succeeded - failed - canceled title: Status capability: type: string title: Capability model: type: string title: Model description: Caller-requested model verbatim (may be 'auto') resolved_model: anyOf: - type: string - type: 'null' title: Resolved Model description: Actual model that ran (null until execution starts; equals model for explicit-model calls) metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata input: anyOf: - additionalProperties: true type: object - type: 'null' title: Input progress: anyOf: - $ref: '#/components/schemas/app__api__v1__schemas__common__TaskProgress' - type: 'null' output: anyOf: - additionalProperties: true type: object - type: 'null' title: Output warnings: items: $ref: '#/components/schemas/TaskWarning' type: array title: Warnings error: anyOf: - $ref: '#/components/schemas/app__api__v1__schemas__common__TaskError' - type: 'null' usage: anyOf: - $ref: '#/components/schemas/UsageObject' - type: 'null' billing: anyOf: - $ref: '#/components/schemas/TaskBilling' - type: 'null' callback: anyOf: - $ref: '#/components/schemas/TaskCallback' - type: 'null' created_at: type: string format: date-time title: Created At started_at: anyOf: - type: string format: date-time - type: 'null' title: Started At deadline_at: anyOf: - type: string format: date-time - type: 'null' title: Deadline At completed_at: anyOf: - type: string format: date-time - type: 'null' title: Completed At cancel_requested_at: anyOf: - type: string format: date-time - type: 'null' title: Cancel Requested At links: $ref: '#/components/schemas/TaskLinks' type: object required: - task_id - status - capability - model - created_at - links title: TaskEnvelope description: 'Standard Task envelope. Returned by every async-creation endpoint, GET /v1/tasks/{id}, and the body of customer callback POSTs.' TaskLinks: properties: self: type: string title: Self cancel: anyOf: - type: string - type: 'null' title: Cancel type: object required: - self title: TaskLinks TaskWarning: properties: code: type: string title: Code description: e.g. option_clamped / auto_routed message: type: string title: Message field: anyOf: - type: string - type: 'null' title: Field type: object required: - code - message title: TaskWarning TextToImageRequest: properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: "Caller-supplied metadata; \u226416 keys, key \u226464 chars,\ \ value \u2264512 chars" callback_url: anyOf: - type: string maxLength: 2048 pattern: ^https:// - type: 'null' title: Callback Url description: HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state callback_signing_key_id: anyOf: - type: string maxLength: 64 minLength: 1 pattern: ^whkey_[A-Za-z0-9]+$ - type: 'null' title: Callback Signing Key Id description: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided. model: type: string enum: - auto - gpt-image-2 - image-01 - image-01-live - wan2.7-image-pro - wan2.7-image - qwen-image-2.0-pro - qwen-image-2.0 title: Model description: Use auto for compatibility-based selection from the configured live candidates. A concrete model is evaluated exactly as requested and is never substituted. default: auto prompt: type: string minLength: 1 pattern: \S title: Prompt description: Required prompt containing at least one non-whitespace character. count: type: integer maximum: 4.0 minimum: 1.0 title: Count description: Requested output image count. The public range is one through four, and the selected model must support the exact count; Beatra does not split the request. default: 1 canvas: oneOf: - $ref: '#/components/schemas/ImagePresetCanvas' - $ref: '#/components/schemas/ImageTargetCanvas' title: Canvas description: Desired output canvas. Presets are quality tiers, and target dimensions may be normalized or vary; inspect output images for actual dimensions. default: type: preset tier: 2K aspect: '16:9' discriminator: propertyName: type mapping: preset: '#/components/schemas/ImagePresetCanvas' target: '#/components/schemas/ImageTargetCanvas' seed: anyOf: - type: integer maximum: 2147483647.0 minimum: 0.0 - type: 'null' title: Seed description: Optional random seed. Supplying it constrains model eligibility; omit it for model-managed randomness. negative_prompt: anyOf: - type: string - type: 'null' title: Negative Prompt description: Optional content or qualities to avoid. Supplying it constrains model eligibility and is rejected when no compatible model is available. enhance_prompt: anyOf: - type: boolean - type: 'null' title: Enhance Prompt description: Omit or use null to retain the selected model's documented default; an explicit boolean constrains model eligibility. palette: anyOf: - items: $ref: '#/components/schemas/ImagePaletteColor' type: array maxItems: 10 minItems: 3 - type: 'null' title: Palette description: Three to ten weighted RGB colors. Runtime validation requires the weights to sum exactly to 1.0000. output_relationship: $ref: '#/components/schemas/ImageOutputRelationship' description: Use independent for unrelated results, or sequence for a related image set. An explicit value constrains model eligibility and is rejected when unsupported. default: independent reasoning: anyOf: - type: boolean - type: 'null' title: Reasoning description: Omit or use null to retain the selected model's documented default; an explicit boolean constrains model eligibility. additionalProperties: false type: object required: - prompt title: TextToImageRequest description: Generate one to four images from a prompt. TextToMusicRequest: properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: Caller-supplied metadata; limited by task creation policy. callback_url: anyOf: - type: string maxLength: 2048 pattern: ^https:// - type: 'null' title: Callback Url description: HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state callback_signing_key_id: anyOf: - type: string maxLength: 64 minLength: 1 pattern: ^whkey_[A-Za-z0-9]+$ - type: 'null' title: Callback Signing Key Id description: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided. model: type: string enum: - auto - minimax-music-3.0 - suno-5.5 title: Model prompt: type: string maxLength: 2000 minLength: 1 title: Prompt description: Music concept, style, mood, genre, or instrumentation prompt. lyrics: anyOf: - type: string maxLength: 5000 - type: 'null' title: Lyrics description: Optional lyrics text. Must be omitted for instrumental music. instrumental: type: boolean title: Instrumental description: When true, generate instrumental music without vocals. default: false title: anyOf: - type: string maxLength: 100 - type: 'null' title: Title model_options: anyOf: - $ref: '#/components/schemas/MusicModelOptions' - type: 'null' description: Options grouped by public music model family. additionalProperties: false type: object required: - model - prompt title: TextToMusicRequest description: Generate music from a prompt and optional lyrics. TextToSpeechRequest: properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: "Caller-supplied metadata; \u226416 keys, key \u226464 chars,\ \ value \u2264512 chars" callback_url: anyOf: - type: string maxLength: 2048 pattern: ^https:// - type: 'null' title: Callback Url description: HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state callback_signing_key_id: anyOf: - type: string maxLength: 64 minLength: 1 pattern: ^whkey_[A-Za-z0-9]+$ - type: 'null' title: Callback Signing Key Id description: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided. model_options: anyOf: - additionalProperties: true type: object - type: 'null' title: Model Options description: Per-model-family passthrough options; opaque to the platform, validated per model voice: type: string title: Voice description: Opaque Beatra voice_id (preset or cloned) input: type: string maxLength: 50000 minLength: 1 title: Input description: Text to synthesize model: type: string enum: - auto - minimax-speech-2.8-hd - minimax-speech-2.8-turbo title: Model description: TTS model; 'auto' picks a model compatible with the voice default: auto language: anyOf: - type: string maxLength: 32 minLength: 2 - type: 'null' title: Language description: Optional BCP-47 language tag, for example zh-CN, yue-HK, or en-US. Read supported_languages from the selected model's catalog card. When omitted, the voice or provider chooses the language. format: type: string enum: - mp3 - wav - flac - opus - pcm title: Format default: mp3 sample_rate: anyOf: - type: integer enum: - 8000 - 16000 - 22050 - 24000 - 32000 - 44100 - type: 'null' title: Sample Rate speed: type: number maximum: 2.0 minimum: 0.5 title: Speed default: 1.0 volume: type: number maximum: 10.0 exclusiveMinimum: 0.0 title: Volume default: 1.0 pitch: type: integer maximum: 12.0 minimum: -12.0 title: Pitch default: 0 emotion: anyOf: - type: string enum: - happy - sad - angry - fearful - disgusted - surprised - calm - type: 'null' title: Emotion description: Provider-neutral discrete speaking emotion additionalProperties: false type: object required: - voice - input title: TextToSpeechRequest TextToVideoRequest: properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: "Caller-supplied metadata; \u226416 keys, key \u226464 chars,\ \ value \u2264512 chars" callback_url: anyOf: - type: string maxLength: 2048 pattern: ^https:// - type: 'null' title: Callback Url description: HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state callback_signing_key_id: anyOf: - type: string maxLength: 64 minLength: 1 pattern: ^whkey_[A-Za-z0-9]+$ - type: 'null' title: Callback Signing Key Id description: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided. model: type: string enum: - auto - minimax-h3 - happyhorse-1.1-t2v - wan2.7-t2v - seedance-2 - seedance-2-fast - seedance-2-mini title: Model description: Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. default: auto negative_prompt: anyOf: - type: string maxLength: 500 - type: 'null' title: Negative Prompt description: Content or qualities to avoid when supported by the selected model. duration: anyOf: - type: integer - type: string const: auto - type: 'null' title: Duration description: Requested output duration as integer seconds, or 'auto' when the selected model may choose its documented duration. Omit to use the selected model default. aspect_ratio: anyOf: - type: string enum: - '16:9' - '9:16' - '1:1' - '4:3' - '3:4' - '4:5' - '5:4' - '21:9' - '9:21' - adaptive - type: 'null' title: Aspect Ratio description: Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. resolution: anyOf: - type: string enum: - 480p - 720p - 1080p - 2k - 4k - type: 'null' title: Resolution description: Requested output short-edge tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. seed: anyOf: - type: integer maximum: 2147483647.0 minimum: 0.0 - type: 'null' title: Seed enhance_prompt: anyOf: - type: boolean - type: 'null' title: Enhance Prompt description: Ask the selected model to improve the prompt before generation. watermark: anyOf: - type: boolean - type: 'null' title: Watermark description: Whether generated video should include the model watermark. generate_audio: anyOf: - type: boolean - type: 'null' title: Generate Audio description: Whether the selected model should generate synchronized audio. web_search: anyOf: - type: boolean - type: 'null' title: Web Search description: Whether the selected model may use web search during generation. return_last_frame: anyOf: - type: boolean - type: 'null' title: Return Last Frame description: Whether to return the generated video's last frame as an image artifact. prompt: type: string maxLength: 7000 minLength: 1 title: Prompt description: Required description of the video to generate without source image or video media. audio: anyOf: - oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/MediaInputDataUri' discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/MediaInputDataUri' url: '#/components/schemas/MediaInputUrl' - type: 'null' title: Audio description: Optional driving audio for models that support audio-conditioned generation. additionalProperties: false type: object required: - prompt title: TextToVideoRequest UploadResponse: properties: object: type: string const: upload title: Object default: upload artifact_id: type: string title: Artifact Id cdn_url: type: string title: Cdn Url mime_type: type: string title: Mime Type media_type: type: string enum: - image - video - audio title: Media Type size_bytes: type: integer title: Size Bytes width: anyOf: - type: integer - type: 'null' title: Width height: anyOf: - type: integer - type: 'null' title: Height duration_ms: anyOf: - type: integer - type: 'null' title: Duration Ms checksum_sha256: type: string title: Checksum Sha256 created_at: type: string format: date-time title: Created At type: object required: - artifact_id - cdn_url - mime_type - media_type - size_bytes - checksum_sha256 - created_at title: UploadResponse description: Returned by both /v1/uploads (201) and de-dup hit (200). UsageLine: properties: meter: type: string title: Meter description: e.g. input_token / output_token / image_count / input_video_second / output_video_second quantity: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Quantity description: "Decimal \u2014 number of meter units consumed" unit: type: string title: Unit description: Display unit, e.g. 'token' / 'image' / 'second' billed_amount_credits: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Billed Amount Credits description: Credits charged for this usage line. Populated by PR-2/3. type: object required: - meter - quantity - unit title: UsageLine UsageObject: properties: input_tokens: anyOf: - type: integer - type: 'null' title: Input Tokens output_tokens: anyOf: - type: integer - type: 'null' title: Output Tokens cache_read_tokens: anyOf: - type: integer - type: 'null' title: Cache Read Tokens cache_creation_tokens: anyOf: - type: integer - type: 'null' title: Cache Creation Tokens reasoning_tokens: anyOf: - type: integer - type: 'null' title: Reasoning Tokens image_count: anyOf: - type: integer - type: 'null' title: Image Count image_pixels: anyOf: - type: integer - type: 'null' title: Image Pixels video_seconds: anyOf: - type: number - type: 'null' title: Video Seconds input_video_seconds: anyOf: - type: number - type: 'null' title: Input Video Seconds description: Authoritative input-video seconds included in settled video usage. output_video_seconds: anyOf: - type: number - type: 'null' title: Output Video Seconds description: Authoritative generated/output-video seconds included in settled video usage. audio_seconds: anyOf: - type: number - type: 'null' title: Audio Seconds characters: anyOf: - type: integer - type: 'null' title: Characters lines: items: $ref: '#/components/schemas/UsageLine' type: array title: Lines credits: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Credits description: Credits charged for this Task. Populated by PR-2 / PR-3. type: object title: UsageObject VideoAspectCard: properties: mode: type: string enum: - explicit_control - source_derived - upstream_fixed - unsupported title: Mode accepts_explicit_value: type: boolean title: Accepts Explicit Value supported_values: items: type: string type: array title: Supported Values default: anyOf: - type: string - type: 'null' title: Default source_role: anyOf: - type: string - type: 'null' title: Source Role additionalProperties: false type: object required: - mode - accepts_explicit_value - supported_values - default - source_role title: VideoAspectCard VideoAutoSelectionCard: properties: request_dependent: type: boolean const: true title: Request Dependent description: Auto selection evaluates the complete request rather than resolving to one fixed model. default: true default_for_omitted_request: anyOf: - type: string - type: 'null' title: Default For Omitted Request description: First live candidate for a request that omits all optional selection controls. candidate_order: items: type: string type: array title: Candidate Order description: Ordered live public candidates; auto selects the first candidate eligible for the request. persisted_selection_field: type: string const: resolved_model title: Persisted Selection Field description: Task field that records the concrete model selected during admission. default: resolved_model additionalProperties: false type: object required: - default_for_omitted_request - candidate_order title: VideoAutoSelectionCard VideoBillableQuantityCard: properties: basis: type: string enum: - admitted_output_duration_seconds - final_output_duration_seconds - reference_video_seconds - capped_reference_video_seconds - source_video_seconds - source_and_reference_video_seconds title: Basis counted_inputs: items: type: string type: array title: Counted Inputs aggregate_max_seconds: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Aggregate Max Seconds per_video_cap_seconds_by_video_count: anyOf: - additionalProperties: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ type: object - type: 'null' title: Per Video Cap Seconds By Video Count additionalProperties: false type: object required: - basis - counted_inputs title: VideoBillableQuantityCard VideoCapabilityDetail: properties: capability: type: string enum: - text_to_video - image_to_video - reference_to_video - frames_to_video - video_edit - video_extend title: Capability endpoint: type: string title: Endpoint input_modality: type: string title: Input Modality output_modality: type: string const: video title: Output Modality default: video execution_mode: type: string const: async title: Execution Mode default: async description: type: string title: Description status: type: string enum: - available - unavailable title: Status auto: $ref: '#/components/schemas/VideoAutoSelectionCard' models: items: $ref: '#/components/schemas/VideoModelCard' type: array title: Models additionalProperties: false type: object required: - capability - endpoint - input_modality - description - status - auto - models title: VideoCapabilityDetail VideoDefaultsCard: properties: resolution: type: string title: Resolution duration: anyOf: - type: integer - type: 'null' title: Duration aspect_ratio: anyOf: - type: string - type: 'null' title: Aspect Ratio generate_audio: anyOf: - type: boolean - type: 'null' title: Generate Audio watermark: anyOf: - type: boolean - type: 'null' title: Watermark web_search: anyOf: - type: boolean - type: 'null' title: Web Search return_last_frame: anyOf: - type: boolean - type: 'null' title: Return Last Frame additionalProperties: false type: object required: - resolution - duration title: VideoDefaultsCard VideoDurationCard: properties: mode: type: string enum: - explicit_control - source_derived - final_duration - upstream_fixed title: Mode required: type: boolean title: Required explicit_override: type: boolean title: Explicit Override supports_auto: type: boolean title: Supports Auto default: false additionalProperties: false type: object required: - mode - required - explicit_override title: VideoDurationCard VideoEditRequest: properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: "Caller-supplied metadata; \u226416 keys, key \u226464 chars,\ \ value \u2264512 chars" callback_url: anyOf: - type: string maxLength: 2048 pattern: ^https:// - type: 'null' title: Callback Url description: HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state callback_signing_key_id: anyOf: - type: string maxLength: 64 minLength: 1 pattern: ^whkey_[A-Za-z0-9]+$ - type: 'null' title: Callback Signing Key Id description: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided. model: type: string enum: - auto - happyhorse-1.0-video-edit - wan2.7-videoedit - seedance-2 - seedance-2-fast - seedance-2-mini title: Model description: Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. default: auto negative_prompt: anyOf: - type: string maxLength: 500 - type: 'null' title: Negative Prompt description: Content or qualities to avoid when supported by the selected model. duration: anyOf: - type: integer - type: string const: auto - type: 'null' title: Duration description: Requested output duration as integer seconds, or 'auto' when the selected model may choose its documented duration. Omit to use the selected model default. aspect_ratio: anyOf: - type: string enum: - '16:9' - '9:16' - '1:1' - '4:3' - '3:4' - '4:5' - '5:4' - '21:9' - '9:21' - adaptive - type: 'null' title: Aspect Ratio description: Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. resolution: anyOf: - type: string enum: - 480p - 720p - 1080p - 2k - 4k - type: 'null' title: Resolution description: Requested output short-edge tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. seed: anyOf: - type: integer maximum: 2147483647.0 minimum: 0.0 - type: 'null' title: Seed enhance_prompt: anyOf: - type: boolean - type: 'null' title: Enhance Prompt description: Ask the selected model to improve the prompt before generation. watermark: anyOf: - type: boolean - type: 'null' title: Watermark description: Whether generated video should include the model watermark. generate_audio: anyOf: - type: boolean - type: 'null' title: Generate Audio description: Whether the selected model should generate synchronized audio. web_search: anyOf: - type: boolean - type: 'null' title: Web Search description: Whether the selected model may use web search during generation. return_last_frame: anyOf: - type: boolean - type: 'null' title: Return Last Frame description: Whether to return the generated video's last frame as an image artifact. source_video: oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/MediaInputDataUri' title: Source Video description: Required video whose existing content will be edited. discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/MediaInputDataUri' url: '#/components/schemas/MediaInputUrl' instruction: type: string maxLength: 5000 minLength: 1 title: Instruction description: Required instruction describing changes to the source video. references: items: $ref: '#/components/schemas/VideoReference' type: array maxItems: 14 title: References description: Optional ordered image, video, or audio references. The selected model must support every supplied reference kind and count. audio_setting: anyOf: - type: string enum: - auto - origin - type: 'null' title: Audio Setting description: 'Optional edit-audio policy: auto lets a compatible model choose, while origin requests preservation of source audio.' additionalProperties: false type: object required: - source_video - instruction title: VideoEditRequest description: Instruction-based video editing with optional multimodal references. VideoExtendRequest: properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: "Caller-supplied metadata; \u226416 keys, key \u226464 chars,\ \ value \u2264512 chars" callback_url: anyOf: - type: string maxLength: 2048 pattern: ^https:// - type: 'null' title: Callback Url description: HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state callback_signing_key_id: anyOf: - type: string maxLength: 64 minLength: 1 pattern: ^whkey_[A-Za-z0-9]+$ - type: 'null' title: Callback Signing Key Id description: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided. model: type: string enum: - auto - wan2.7-i2v - seedance-2 - seedance-2-fast - seedance-2-mini title: Model description: Use auto for request-dependent selection from the ordered live candidates. A concrete model is evaluated exactly as requested and is never substituted. default: auto negative_prompt: anyOf: - type: string maxLength: 500 - type: 'null' title: Negative Prompt description: Content or qualities to avoid when supported by the selected model. duration: type: integer maximum: 15.0 minimum: 2.0 title: Duration description: Required final returned-video duration in integer seconds. It must exceed the trusted source-video duration; model-specific admission may narrow the range. aspect_ratio: anyOf: - type: string enum: - '16:9' - '9:16' - '1:1' - '4:3' - '3:4' - '4:5' - '5:4' - '21:9' - '9:21' - adaptive - type: 'null' title: Aspect Ratio description: Explicit output ratio when the selected model accepts it. Omit for a declared model default, source-derived ratio, or fixed model behavior. resolution: anyOf: - type: string enum: - 480p - 720p - 1080p - 2k - 4k - type: 'null' title: Resolution description: Requested output short-edge tier. Omit to use the selected model's declared default; unsupported tiers are rejected rather than coerced. seed: anyOf: - type: integer maximum: 2147483647.0 minimum: 0.0 - type: 'null' title: Seed enhance_prompt: anyOf: - type: boolean - type: 'null' title: Enhance Prompt description: Ask the selected model to improve the prompt before generation. watermark: anyOf: - type: boolean - type: 'null' title: Watermark description: Whether generated video should include the model watermark. generate_audio: anyOf: - type: boolean - type: 'null' title: Generate Audio description: Whether the selected model should generate synchronized audio. web_search: anyOf: - type: boolean - type: 'null' title: Web Search description: Whether the selected model may use web search during generation. return_last_frame: anyOf: - type: boolean - type: 'null' title: Return Last Frame description: Whether to return the generated video's last frame as an image artifact. video: oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/MediaInputDataUri' title: Video description: The single source video to continue. discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/MediaInputDataUri' url: '#/components/schemas/MediaInputUrl' direction: type: string enum: - before - after title: Direction description: Generate new content immediately before or after the source video's content. instruction: type: string maxLength: 5000 minLength: 1 title: Instruction description: Required instruction describing how the source video should continue. references: items: $ref: '#/components/schemas/VideoReference' type: array maxItems: 12 title: References description: Optional ordered image or audio references. Additional video references are forbidden because this operation accepts exactly one source video. additionalProperties: false type: object required: - duration - video - direction - instruction title: VideoExtendRequest description: Generate footage immediately before or after one source video. VideoModelCard: properties: schema_version: type: string const: video-interface.v1 title: Schema Version default: video-interface.v1 model: type: string title: Model display_name: type: string title: Display Name owned_by: type: string const: Beatra title: Owned By default: Beatra capability: type: string enum: - text_to_video - image_to_video - reference_to_video - frames_to_video - video_edit - video_extend title: Capability status: type: string const: available title: Status default: available controls: items: type: string type: array title: Controls skus: items: $ref: '#/components/schemas/VideoSKUCard' type: array minItems: 1 title: Skus defaults: $ref: '#/components/schemas/VideoDefaultsCard' aspect: $ref: '#/components/schemas/VideoAspectCard' duration: $ref: '#/components/schemas/VideoDurationCard' prompt_required: type: boolean title: Prompt Required prompt_max_units: type: integer exclusiveMinimum: 0.0 title: Prompt Max Units prompt_unit: type: string enum: - characters - happyhorse_weighted title: Prompt Unit reference_kinds: items: type: string type: array title: Reference Kinds reference_roles: items: type: string type: array title: Reference Roles max_references: type: integer minimum: 0.0 title: Max References reference_limits: anyOf: - $ref: '#/components/schemas/VideoReferenceLimitsCard' - type: 'null' media: additionalProperties: true type: object title: Media pricing: items: $ref: '#/components/schemas/VideoPricingOption' type: array minItems: 1 title: Pricing additionalProperties: false type: object required: - model - display_name - capability - controls - skus - defaults - aspect - duration - prompt_required - prompt_max_units - prompt_unit - reference_kinds - reference_roles - max_references - media - pricing title: VideoModelCard VideoModelDetail: properties: model: type: string title: Model display_name: type: string title: Display Name owned_by: type: string const: Beatra title: Owned By default: Beatra description: type: string title: Description status: type: string enum: - available - unavailable title: Status interfaces: items: $ref: '#/components/schemas/VideoModelCard' type: array title: Interfaces additionalProperties: false type: object required: - model - display_name - description - status - interfaces title: VideoModelDetail VideoPricingOption: properties: meter: type: string enum: - input_video_second - output_video_second title: Meter unit: type: string const: second title: Unit default: second unit_price_credits: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Unit Price Credits scale: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Scale resolution: type: string title: Resolution duration_seconds: items: type: integer type: array minItems: 1 title: Duration Seconds applicability: type: string enum: - video_input_present - always title: Applicability billable_quantity: $ref: '#/components/schemas/VideoBillableQuantityCard' estimate_formula: type: string const: (unit_price_credits * billable_quantity) / scale title: Estimate Formula default: (unit_price_credits * billable_quantity) / scale additionalProperties: false type: object required: - meter - unit_price_credits - scale - resolution - duration_seconds - applicability - billable_quantity title: VideoPricingOption VideoReference: properties: kind: type: string enum: - image - video - audio title: Kind description: Declares whether this ordered reference is image, video, or audio. media: oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/MediaInputDataUri' title: Media description: Artifact, HTTPS URL, or data URI for this ordered reference. discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/MediaInputDataUri' url: '#/components/schemas/MediaInputUrl' role: anyOf: - type: string enum: - subject - style - character - product - background - pose - type: 'null' title: Role description: Optional semantic hint. Set it only when `beatra.models.list` advertises top-level `reference_roles` for the selected typed video model card; otherwise omit it and identify ordered references in the prompt. reference_voice: anyOf: - oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/MediaInputDataUri' discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/MediaInputDataUri' url: '#/components/schemas/MediaInputUrl' - type: 'null' title: Reference Voice description: Optional voice reference associated with this item when the selected model supports it. additionalProperties: false type: object required: - kind - media title: VideoReference description: One ordered visual reference with optional semantic and voice guidance. VideoReferenceLimitsCard: properties: image: type: integer minimum: 0.0 title: Image video: type: integer minimum: 0.0 title: Video audio: type: integer minimum: 0.0 title: Audio video_total_seconds: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Video Total Seconds audio_total_seconds: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Audio Total Seconds audio_requires_image_or_video: type: boolean title: Audio Requires Image Or Video default: false additionalProperties: false type: object required: - image - video - audio title: VideoReferenceLimitsCard VideoSKUCard: properties: resolution: type: string title: Resolution duration_seconds: type: integer title: Duration Seconds additionalProperties: false type: object required: - resolution - duration_seconds title: VideoSKUCard Voice: properties: voice_id: type: string title: Voice Id description: Opaque Beatra voice handle display_name: type: string title: Display Name category: type: string enum: - preset - cloned title: Category language: anyOf: - type: string - type: 'null' title: Language languages_supported: items: type: string type: array title: Languages Supported gender: anyOf: - type: string enum: - male - female - neutral - type: 'null' title: Gender age: anyOf: - type: string enum: - adult - child - elder - type: 'null' title: Age accent: anyOf: - type: string - type: 'null' title: Accent use_case: items: type: string type: array title: Use Case preview_url: anyOf: - type: string - type: 'null' title: Preview Url compatible_models: items: type: string type: array title: Compatible Models description: Models this voice currently resolves on (informational; 'auto' always works) status: type: string enum: - processing - ready - failed title: Status default: ready created_at: anyOf: - type: string - type: 'null' title: Created At type: object required: - voice_id - display_name - category title: Voice VoiceCloneConstraintsCard: properties: accepted_sample_kinds: items: type: string enum: - artifact - data_uri - https_url type: array title: Accepted Sample Kinds sample_min_seconds: type: integer const: 10 title: Sample Min Seconds default: 10 sample_max_seconds: type: integer const: 300 title: Sample Max Seconds default: 300 sample_max_bytes: type: integer const: 20971520 title: Sample Max Bytes default: 20971520 consent_attestation_required: type: boolean const: true title: Consent Attestation Required default: true automatic_formal_activation: type: boolean const: true title: Automatic Formal Activation default: true additionalProperties: false type: object required: - accepted_sample_kinds title: VoiceCloneConstraintsCard VoiceCloneRequest: properties: metadata: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Metadata description: "Caller-supplied metadata; \u226416 keys, key \u226464 chars,\ \ value \u2264512 chars" callback_url: anyOf: - type: string maxLength: 2048 pattern: ^https:// - type: 'null' title: Callback Url description: HTTPS URL Beatra will POST the final Task envelope to when the Task reaches a terminal state callback_signing_key_id: anyOf: - type: string maxLength: 64 minLength: 1 pattern: ^whkey_[A-Za-z0-9]+$ - type: 'null' title: Callback Signing Key Id description: Optional standalone callback signing key. Omit for unsigned callback delivery; requires callback_url when provided. model_options: anyOf: - additionalProperties: true type: object - type: 'null' title: Model Options description: Per-model-family passthrough options; opaque to the platform, validated per model sample: oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/MediaInputDataUri' title: Sample description: Clean single-speaker voice sample (uploaded artifact or HTTPS URL), ~10s-5min discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/MediaInputDataUri' url: '#/components/schemas/MediaInputUrl' display_name: type: string maxLength: 255 minLength: 1 title: Display Name model: type: string enum: - auto - minimax-voice-clone title: Model description: Clone engine; 'auto' lets the platform choose default: auto language: anyOf: - type: string maxLength: 32 minLength: 2 - type: 'null' title: Language description: Optional BCP-47 language hint for the cloned voice consent_attested: type: boolean const: true title: Consent Attested description: Caller asserts it has the rights to clone this voice. Recorded, not verified. additionalProperties: false type: object required: - sample - display_name - consent_attested title: VoiceCloneRequest VoiceList: properties: object: type: string const: list title: Object default: list data: items: $ref: '#/components/schemas/Voice' type: array title: Data type: object required: - data title: VoiceList app__api__v1__schemas__common__TaskError: properties: code: type: string title: Code description: Stable machine-readable public error code. type: type: string title: Type description: Stable public error family. message: type: string title: Message description: Human-readable safe failure reason. retryable: type: boolean title: Retryable description: Whether the same logical request may succeed when retried unchanged. param: anyOf: - type: string - type: 'null' title: Param description: JSON Pointer to the relevant request or output field. details: anyOf: - additionalProperties: true type: object - type: 'null' title: Details description: Provider-neutral expected, received, supported, or candidate failure facts. request_id: type: string title: Request Id description: Request trace identifier for support and correlation. type: object required: - code - type - message - retryable - request_id title: TaskError app__api__v1__schemas__common__TaskProgress: properties: percent: anyOf: - type: integer maximum: 100.0 minimum: 0.0 - type: 'null' title: Percent stage: anyOf: - type: string - type: 'null' title: Stage message: anyOf: - type: string - type: 'null' title: Message type: object title: TaskProgress app__api__v1__schemas__tasks__TaskListResponse: properties: object: type: string const: list title: Object default: list data: items: additionalProperties: true type: object type: array title: Data description: TaskSummary[] by default; TaskEnvelope[] with expand next_cursor: anyOf: - type: string - type: 'null' title: Next Cursor has_more: type: boolean title: Has More default: false type: object required: - data title: TaskListResponse description: 'List response wrapper. Uses TaskSummary by default. Clients can opt-in to richer detail via `?expand=output,usage,billing,callback,input` or `?expand=all`. When expand is in effect, items become full TaskEnvelope.'