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' - $ref: '#/components/schemas/UnderstandingCapabilityDetail' - $ref: '#/components/schemas/VideoPromptEnhancementCapabilityDetail' 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' - $ref: '#/components/schemas/UnderstandingModelDetail' 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/images/responses: post: tags: - images summary: Image understanding (image_to_text) operationId: images_responses_v1_images_responses_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/ImageToTextRequest' 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/prompts/enhance: post: tags: - videos summary: Enhance a video prompt from optional multimodal context description: Create an asynchronous text-only prompt-enhancement task. Successful tasks are charged after completion from actual input and output tokens; this call does not generate a video. The compatibility model field is ignored. operationId: videos_enhance_prompt_v1_videos_prompts_enhance_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/VideoPromptEnhancementRequest' 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 toward a strict last frame description: Create an asynchronous video task constrained by a required last frame and an optional first frame. 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/videos/responses: post: tags: - videos summary: Video understanding (video_to_text) operationId: videos_responses_v1_videos_responses_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/VideoToTextRequest' 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 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: $ref: '#/components/schemas/ImageInterfaceCard' 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 - wan3.0-video - wan3.0-video-prime - wan2.7-i2v - seedance-2 - seedance-2-fast - seedance-2-mini - seedance-2.5 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 model-defined output resolution 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 rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written. 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. output_format: anyOf: - type: string enum: - mp4 - mov - type: 'null' title: Output Format description: Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. prompt: anyOf: - type: string maxLength: 20000 - type: 'null' title: Prompt description: Optional instructions for the motion ending at the required last frame. first_frame: 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: First Frame description: Optional image that must be the video's first frame. Omit it for a last-frame-only request when the selected model advertises that input combination. 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: - 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.5-flare - gpt-image-2.5-sunburst - gpt-image-2 - image-01-live - wan2.7-image-pro - wan2.7-image - qwen-image-3.0-pro - qwen-image-3.0 - 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: Ask the model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written; 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: 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 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 - 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. 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. ImagePriceOptionCard: properties: dimensions: additionalProperties: type: string type: object title: Dimensions unit_credits: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Unit Credits additionalProperties: false type: object required: - dimensions - unit_credits title: ImagePriceOptionCard ImagePricingCard: properties: meter: type: string const: image_count title: Meter default: image_count unit: type: string const: image title: Unit default: image billing_basis: type: string const: successful_image_count title: Billing Basis default: successful_image_count estimate_formula: type: string const: unit_credits * successful_image_count title: Estimate Formula default: unit_credits * successful_image_count options: items: $ref: '#/components/schemas/ImagePriceOptionCard' type: array minItems: 1 title: Options additionalProperties: false type: object required: - options 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.5-flare - gpt-image-2.5-sunburst - gpt-image-2 - image-01-live - wan2.7-image-pro - wan2.7-image - qwen-image-3.0-pro - qwen-image-3.0 - 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: Ask the model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written; 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. ImageToTextRequest: 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 title: Model prompt: type: string maxLength: 4000 title: Prompt images: items: oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/ImageUnderstandingDataUri' discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/ImageUnderstandingDataUri' url: '#/components/schemas/MediaInputUrl' type: array maxItems: 8 minItems: 1 title: Images description: One through eight ordered image inputs. Each admitted image is billed once. detail: type: string enum: - default - low - high title: Detail description: Visual detail preference. It does not change Beatra's per-image price. default: default response_format: anyOf: - type: string enum: - text - json - type: 'null' title: Response Format temperature: anyOf: - type: number maximum: 2.0 minimum: 0.0 - type: 'null' title: Temperature additionalProperties: false type: object required: - model - prompt - images title: ImageToTextRequest description: Vision Q&A or captioning; unrelated to the image creation contract. 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 - wan3.0-video - wan3.0-video-prime - happyhorse-1.1-i2v - wan2.7-i2v - seedance-2 - seedance-2-fast - seedance-2-mini - seedance-2.5 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 model-defined output resolution 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 rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written. 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. output_format: anyOf: - type: string enum: - mp4 - mov - type: 'null' title: Output Format description: Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. prompt: anyOf: - type: string maxLength: 20000 - 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. ImageUnderstandingDataUri: properties: type: type: string const: data_uri title: Type data: type: string maxLength: 13981144 title: Data description: Base64 data URI. Decoded image content is limited to 10 MiB. type: object required: - type - data title: ImageUnderstandingDataUri 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: $ref: '#/components/schemas/ImageInterfaceCard' 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 negative_tags_max_characters: anyOf: - type: integer minimum: 1.0 - type: 'null' title: Negative Tags Max Characters description: Maximum characters for model_options.suno.negative_tags when that control is supported. 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-6 title: Model prompt: type: string maxLength: 2000 minLength: 1 title: Prompt description: 'Style, mood, genre, and instrumentation. When lyrics are supplied (or Suno custom mode is on) this maps to the provider''s style-conditioning field; otherwise it is the song description the model writes the song from. Either way it is not an instruction field: execution directives written here (for example "do not omit anything", "sing it verbatim", "make chapter three differ from chapter one") are not read as instructions and will not be obeyed. Put the words to be sung in `lyrics`, or set `instrumental` to true for a track with no vocals.' 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 - wan3.0-video - wan3.0-video-prime - happyhorse-1.1-r2v - wan2.7-r2v - seedance-2 - seedance-2-fast - seedance-2-mini - seedance-2.5 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 model-defined output resolution 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 rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written. 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. output_format: anyOf: - type: string enum: - mp4 - mov - type: 'null' title: Output Format description: Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. prompt: anyOf: - type: string maxLength: 20000 - 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: 50 minItems: 1 title: References description: One to fifty ordered image, video, or audio references. Model-specific kind, count, duration, and combination limits still apply. additionalProperties: false type: object required: - references title: ReferenceToVideoRequest SocialTaskIdentity: properties: platform: type: string title: Platform operation_key: type: string title: Operation Key operation_name: type: string title: Operation Name schema_hash: type: string title: Schema Hash type: object required: - platform - operation_key - operation_name - schema_hash title: SocialTaskIdentity 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/AudioNumberRange' 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: 200 - type: 'null' title: Negative Tags description: Suno traits to exclude; limited independently from prompt, lyrics, and title. 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 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. granted_credits: anyOf: - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ - type: 'null' title: Granted Credits description: Credits on this Task covered by a directed grant rather than by the wallet, net of any revocation. Absent when no grant applied. grant_source: anyOf: - type: string - type: 'null' title: Grant Source description: Which grant covered it. Present exactly when granted_credits is. 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 minus granted_credits. This is the number to report as what the Task cost.' 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: Stable Beatra-owned callback delivery failure summary. 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 workload_type: type: string enum: - model - social_operation title: Workload Type default: model model: anyOf: - type: string - type: 'null' title: Model description: Caller-requested model verbatim (may be 'auto'). Null for social_operation tasks. 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) model_selection_reason: type: 'null' title: Model Selection Reason description: Deprecated. Always null. deprecated: true social: anyOf: - $ref: '#/components/schemas/SocialTaskIdentity' - type: 'null' 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 - 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 assets: anyOf: - type: string - type: 'null' title: Assets description: Absolute customer-console URL for viewing and managing the generated artifacts. 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.5-flare - gpt-image-2.5-sunburst - gpt-image-2 - image-01-live - wan2.7-image-pro - wan2.7-image - qwen-image-3.0-pro - qwen-image-3.0 - 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: Ask the model to rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written; 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-6 title: Model prompt: type: string maxLength: 2000 minLength: 1 title: Prompt description: 'Style, mood, genre, and instrumentation. When lyrics are supplied (or Suno custom mode is on) this maps to the provider''s style-conditioning field; otherwise it is the song description the model writes the song from. Either way it is not an instruction field: execution directives written here (for example "do not omit anything", "sing it verbatim", "make chapter three differ from chapter one") are not read as instructions and will not be obeyed. Put the words to be sung in `lyrics`, or set `instrumental` to true for a track with no vocals.' 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: number maximum: 1.0 minimum: -1.0 title: Pitch description: 'Pitch adjustment from -1 to 1: 0 keeps the voice''s original pitch, -1 is the lowest and 1 the highest the selected model supports. Use decimals such as 0.25 or -0.5 for subtle tuning.' default: 0.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 - wan3.0-video - wan3.0-video-prime - happyhorse-1.1-t2v - wan2.7-t2v - seedance-2 - seedance-2-fast - seedance-2-mini - seedance-2.5 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 model-defined output resolution 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 rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written. 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. output_format: anyOf: - type: string enum: - mp4 - mov - type: 'null' title: Output Format description: Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. prompt: type: string maxLength: 20000 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 UnderstandingAutoSelectionCard: properties: request_dependent: type: boolean const: true title: Request Dependent default: true default_for_omitted_request: anyOf: - type: string - type: 'null' title: Default For Omitted Request candidate_order: items: type: string type: array title: Candidate Order additionalProperties: false type: object required: - default_for_omitted_request - candidate_order title: UnderstandingAutoSelectionCard UnderstandingCapabilityDetail: properties: schema_version: type: string const: understanding-interface.v1 title: Schema Version default: understanding-interface.v1 capability: type: string enum: - image_to_text - video_to_text title: Capability endpoint: type: string title: Endpoint input_modality: type: string title: Input Modality output_modality: type: string const: text title: Output Modality default: text execution_mode: type: string const: sync_long title: Execution Mode default: sync_long description: type: string title: Description status: type: string enum: - available - unavailable title: Status auto: $ref: '#/components/schemas/UnderstandingAutoSelectionCard' models: items: $ref: '#/components/schemas/UnderstandingModelCard' type: array title: Models additionalProperties: false type: object required: - capability - endpoint - input_modality - description - status - auto - models title: UnderstandingCapabilityDetail UnderstandingDetailCard: properties: default: type: string const: default title: Default default: default values: items: type: string enum: - default - low - high type: array title: Values affects_price: type: boolean const: false title: Affects Price default: false additionalProperties: false type: object title: UnderstandingDetailCard UnderstandingMediaConstraintsCard: properties: kind: type: string enum: - image - video title: Kind accepted_kinds: items: type: string enum: - artifact - data_uri - https_url type: array title: Accepted Kinds min_items: type: integer const: 1 title: Min Items default: 1 max_items: type: integer maximum: 8.0 minimum: 1.0 title: Max Items max_bytes_each: type: integer exclusiveMinimum: 0.0 title: Max Bytes Each max_duration_seconds: anyOf: - type: integer exclusiveMinimum: 0.0 - type: 'null' title: Max Duration Seconds sampling_fps: anyOf: - type: integer exclusiveMinimum: 0.0 - type: 'null' title: Sampling Fps additionalProperties: false type: object required: - kind - accepted_kinds - max_items - max_bytes_each title: UnderstandingMediaConstraintsCard UnderstandingModelCard: properties: schema_version: type: string const: understanding-interface.v1 title: Schema Version default: understanding-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: - image_to_text - video_to_text title: Capability status: type: string const: available title: Status default: available controls: items: type: string type: array title: Controls media: $ref: '#/components/schemas/UnderstandingMediaConstraintsCard' detail: $ref: '#/components/schemas/UnderstandingDetailCard' thinking: $ref: '#/components/schemas/UnderstandingThinkingCard' pricing: items: $ref: '#/components/schemas/UnderstandingPricingCard' type: array minItems: 1 title: Pricing additionalProperties: false type: object required: - model - display_name - capability - controls - media - detail - thinking - pricing title: UnderstandingModelCard UnderstandingModelDetail: 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/UnderstandingModelCard' type: array title: Interfaces additionalProperties: false type: object required: - model - display_name - description - status - interfaces title: UnderstandingModelDetail UnderstandingPricingCard: properties: meter: type: string enum: - image_count - input_video_second title: Meter unit: type: string enum: - image - second 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: - admitted_image_count - ceil_admitted_input_video_seconds 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: UnderstandingPricingCard UnderstandingThinkingCard: properties: public_control: type: boolean const: false title: Public Control default: false mode: type: string enum: - adaptive - model_default title: Mode additionalProperties: false type: object required: - mode title: UnderstandingThinkingCard 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 - wan3.0-video - wan3.0-video-prime - happyhorse-1.0-video-edit - wan2.7-videoedit - seedance-2 - seedance-2-fast - seedance-2-mini - seedance-2.5 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 model-defined output resolution 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 rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written. 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. output_format: anyOf: - type: string enum: - mp4 - mov - type: 'null' title: Output Format description: Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. 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: 20000 minLength: 1 title: Instruction description: Required instruction describing changes to the source video. references: items: $ref: '#/components/schemas/VideoReference' type: array maxItems: 49 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 - wan3.0-video - wan3.0-video-prime - wan2.7-i2v - seedance-2 - seedance-2-fast - seedance-2-mini - seedance-2.5 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: 30.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 model-defined output resolution 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 rewrite the prompt before generation. Omit or use null to keep the prompt exactly as written. 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. output_format: anyOf: - type: string enum: - mp4 - mov - type: 'null' title: Output Format description: Optional output container. Omit or use mp4 for the existing default; models that advertise mov can return MOV without transcoding. 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: 20000 minLength: 1 title: Instruction description: Required instruction describing how the source video should continue. references: items: $ref: '#/components/schemas/VideoReference' type: array maxItems: 49 title: References description: Optional ordered image, video, or audio references. The selected model must support every supplied reference kind and count. 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 output_formats: items: type: string enum: - mp4 - mov type: array minItems: 1 title: Output Formats 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' input_combinations: items: items: type: string type: array type: array title: Input Combinations output_audio: anyOf: - $ref: '#/components/schemas/VideoOutputAudioCard' - 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 - output_formats - 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: anyOf: - $ref: '#/components/schemas/VideoModelCard' - $ref: '#/components/schemas/VideoPromptEnhancementModelCard' type: array title: Interfaces additionalProperties: false type: object required: - model - display_name - description - status - interfaces title: VideoModelDetail VideoOutputAudioCard: properties: included: type: boolean title: Included channel_layout: anyOf: - type: string const: stereo - type: 'null' title: Channel Layout source: anyOf: - type: string const: model_generated - type: 'null' title: Source additionalProperties: false type: object required: - included title: VideoOutputAudioCard 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 VideoPromptEnhancementAutoCard: properties: request_dependent: type: boolean const: false title: Request Dependent default: false model_input_ignored: type: boolean const: true title: Model Input Ignored default: true resolved_model: type: string title: Resolved Model persisted_selection_field: type: string const: resolved_model title: Persisted Selection Field default: resolved_model additionalProperties: false type: object required: - resolved_model title: VideoPromptEnhancementAutoCard VideoPromptEnhancementCapabilityDetail: properties: capability: type: string const: video_prompt_enhancement title: Capability default: video_prompt_enhancement endpoint: type: string title: Endpoint input_modality: type: string title: Input Modality output_modality: type: string const: text title: Output Modality default: text 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/VideoPromptEnhancementAutoCard' models: items: $ref: '#/components/schemas/VideoPromptEnhancementModelCard' type: array title: Models additionalProperties: false type: object required: - endpoint - input_modality - description - status - auto - models title: VideoPromptEnhancementCapabilityDetail VideoPromptEnhancementModelCard: properties: schema_version: type: string const: video-prompt-enhancement.v1 title: Schema Version default: video-prompt-enhancement.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 const: video_prompt_enhancement title: Capability default: video_prompt_enhancement status: type: string const: available title: Status default: available controls: items: type: string type: array title: Controls duration_seconds: additionalProperties: type: integer type: object title: Duration Seconds aspect_ratios: items: type: string type: array title: Aspect Ratios max_references: type: integer title: Max References default: 11 reference_limits: $ref: '#/components/schemas/VideoReferenceLimitsCard' billing_mode: type: string const: postpaid title: Billing Mode default: postpaid billing_basis: type: string const: successful_provider_reported_tokens title: Billing Basis default: successful_provider_reported_tokens pricing: items: $ref: '#/components/schemas/VideoPromptPricingOption' type: array maxItems: 2 minItems: 2 title: Pricing additionalProperties: false type: object required: - model - display_name - controls - duration_seconds - aspect_ratios - reference_limits - pricing title: VideoPromptEnhancementModelCard VideoPromptEnhancementRequest: 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: title: Model description: Compatibility input only. Its value and type are ignored in the first release; Beatra resolves the available prompt-enhancement model internally. default: auto prompt: type: string maxLength: 7000 minLength: 1 title: Prompt description: Required creative intent to expand into a production-ready video prompt. duration: type: integer maximum: 15.0 minimum: 4.0 title: Duration description: Target video duration in integer seconds. aspect_ratio: type: string enum: - adaptive - '21:9' - '16:9' - '4:3' - '1:1' - '3:4' - '9:16' title: Aspect Ratio description: Target video aspect ratio. Text-only requests cannot use adaptive. first_frame: 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: First Frame description: Optional strict first-frame context image. last_frame: 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: Last Frame description: Optional strict last-frame context image. references: items: $ref: '#/components/schemas/VideoReference' type: array maxItems: 11 title: References description: Optional ordered image, video, or audio context. Reference mode and strict-frame mode are mutually exclusive. additionalProperties: false type: object required: - prompt - duration - aspect_ratio title: VideoPromptEnhancementRequest description: Model-neutral multimodal context for one enhanced video prompt. VideoPromptPricingOption: properties: meter: type: string enum: - input_token - output_token title: Meter unit: type: string const: token title: Unit default: token unit_price_credits: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Unit Price Credits scale: type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Scale additionalProperties: false type: object required: - meter - unit_price_credits - scale title: VideoPromptPricingOption 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 VideoToTextRequest: 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 title: Model description: Video-understanding model (`auto` or `MiniMax-M3`). prompt: type: string maxLength: 32000 title: Prompt video: oneOf: - $ref: '#/components/schemas/MediaInputUrl' - $ref: '#/components/schemas/MediaInputArtifact' - $ref: '#/components/schemas/VideoUnderstandingDataUri' title: Video description: The single video input. Beatra samples internally at 1 fps, 0.5 fps from 120 seconds, and 0.2 fps from 240 seconds. discriminator: propertyName: type mapping: artifact: '#/components/schemas/MediaInputArtifact' data_uri: '#/components/schemas/VideoUnderstandingDataUri' url: '#/components/schemas/MediaInputUrl' detail: type: string enum: - default - low - high title: Detail description: Visual detail preference. It does not change Beatra's per-second price. default: default response_format: anyOf: - type: string enum: - text - json - type: 'null' title: Response Format temperature: anyOf: - type: number maximum: 2.0 minimum: 0.0 - type: 'null' title: Temperature additionalProperties: false type: object required: - model - prompt - video title: VideoToTextRequest VideoUnderstandingDataUri: properties: type: type: string const: data_uri title: Type data: type: string maxLength: 69905196 title: Data description: Base64 data URI. Decoded video content is limited to 50 MiB. type: object required: - type - data title: VideoUnderstandingDataUri 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 format: date-time - 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.'