---
title: "Capability detail with typed media interface cards"
method: GET
path: "/v1/catalog/capabilities/{capability}"
tags: ["catalog"]
---

# Capability detail with typed media interface cards

`GET /v1/catalog/capabilities/{capability}`

## Request

- Base URL: `https://api.beatra.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.beatra.ai/v1/catalog/capabilities/{capability}`
- Auth: none declared

## Path parameters

- `capability` string, required

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- union
  - CapabilityDetail
    - `capability` 'text_to_image' | 'image_to_image' | 'image_edit', required
    - `endpoint` string, required
    - `input_modality` string, required
    - `output_modality` 'image'
    - `execution_mode` 'async'
    - `description` string, required
    - `status` 'available' | 'unavailable'
    - `auto` ImageAutoSelectionCard, required
      - `default_model` 'auto'
      - `basic_request_preference` string, required
      - `request_dependent` true
      - `persisted_selection_field` 'resolved_model'
      - `description` string, required
    - `models` ImageInterfaceCard[], required
      - `model` string, required
      - `display_name` string, required
      - `owned_by` 'beatra'
      - `capability` 'text_to_image' | 'image_to_image' | 'image_edit', required
      - `status` 'available'
      - `controls` ImageControlCard[], required
        - `field` string, required
        - `value_type` 'string' | 'integer' | 'boolean' | 'enum' | 'canvas' | 'image_collection' | 'palette' | 'region_collection', required
        - `required` boolean, required
        - `nullable` boolean, required
        - `default` union, required
          - string
          - integer
          - boolean
          - object
        - `model_default` boolean, nullable
        - `omitted_behavior` 'invalid' | 'use_public_default' | 'use_model_default' | 'same_as_omitted' | 'random', required
        - `null_behavior` 'invalid' | 'same_as_omitted' | 'use_model_default', required
        - `allowed_values` string[], nullable
        - `minimum` union
          - integer
          - number
        - `maximum` union
          - integer
          - number
        - `min_items` integer, nullable
        - `max_items` integer, nullable
        - `max_length` integer, nullable
      - `prompt` ImagePromptCard, required
        - `limit` integer, required
        - `unit` 'characters' | 'qwen_tokens', required
        - `overflow` 'reject'
        - `languages` string[], required
        - `counter` 'unicode_characters' | 'qwen_open_family_proxy', required
        - `counter_is_exact` boolean, required
        - `counter_unavailable_behavior` 'reject'
      - `inputs` ImageInputsCard, required
        - `minimum_count` integer, required
        - `public_max_count` integer, required
        - `native_max_count` integer, required
        - `formats` string[], required
        - `hard_constraints` ImageInputHardConstraints, required
          - `max_bytes` integer, nullable, required
          - `edge_pixels` ImageIntegerRange, required
            - `minimum` integer, required
            - `maximum` integer, required
          - `aspect_ratio` ImageAspectRange, required
            - `minimum` string, required
            - `maximum` string, required
          - `alpha` 'allowed' | 'reject_png_alpha', required
        - `recommendations` ImageInputRecommendations, required
          - `edge_pixels` ImageIntegerRange, required
            - `minimum` integer, required
            - `maximum` integer, required
        - `animation` object, required
        - `transport` ImageInputTransportCard, required
          - `accepted_kinds` string[], required
          - `https_only` boolean, required
          - `data_uri_max_encoded_length` integer, nullable, required
        - `ordering` 'none' | 'ordered_references' | 'first_is_base_remaining_are_references', required
        - `source_aspect_anchor` 'none' | 'first_input' | 'last_input', required
      - `outputs` ImageOutputsCard, required
        - `public_max_count` integer, required
        - `native_max_independent_count` integer, required
        - `native_max_sequence_count` integer, nullable
        - `relationships` string[], required
        - `format` 'image/png'
      - `canvas` ImageCanvasCard, required
        - `default` object, required
        - `preset_tiers` string[], required
        - `target` ImageTargetCanvasCard, required
          - `supported` boolean, required
          - `minimum_total_pixels` integer, required
          - `maximum_total_pixels` integer, required
          - `minimum_aspect_ratio` string, nullable, required
          - `maximum_aspect_ratio` string, nullable, required
          - `normalization_multiple` integer, nullable, required
          - `actual_dimensions_may_differ` boolean, required
        - `source_aspect_anchor` 'none' | 'first_input' | 'last_input', required
      - `rules` ImageInterfaceRule[], required
        - `id` string, required
        - `when` ImageRulePredicate[], required
          - `field` string, required
          - `operator` 'equals' | 'present' | 'greater_than', required
          - `value` union
            - string
            - integer
            - boolean
            - string[]
        - `effect` ImageRuleEffect, required
          - `type` 'allow' | 'forbid' | 'limit' | 'require', required
          - `field` string, required
          - `value` union
            - string
            - integer
            - boolean
            - string[]
      - `pricing` ImagePricingCard, required
        - `meter` 'image_count'
        - `unit` 'image'
        - `billing_basis` 'successful_image_count'
        - `estimate_formula` 'unit_credits * successful_image_count'
        - `options` ImagePriceOptionCard[], required
          - `dimensions` object, required
          - `unit_credits` string, required
      - `auto` ImageAutoSelectionCard, required
        - `default_model` 'auto'
        - `basic_request_preference` string, required
        - `request_dependent` true
        - `persisted_selection_field` 'resolved_model'
        - `description` string, required
    - `max_output_images` integer, nullable
    - `max_canvas_pixels` integer, nullable
    - `starting_credits` string, nullable
  - VideoCapabilityDetail
    - `capability` 'text_to_video' | 'image_to_video' | 'reference_to_video' | 'frames_to_video' | 'video_edit' | 'video_extend', required
    - `endpoint` string, required
    - `input_modality` string, required
    - `output_modality` 'video'
    - `execution_mode` 'async'
    - `description` string, required
    - `status` 'available' | 'unavailable', required
    - `auto` VideoAutoSelectionCard, required
      - `request_dependent` true: Auto selection evaluates the complete request rather than resolving to one fixed model.
      - `default_for_omitted_request` string, nullable, required: First live candidate for a request that omits all optional selection controls.
      - `candidate_order` string[], required: Ordered live public candidates; auto selects the first candidate eligible for the request.
      - `persisted_selection_field` 'resolved_model': Task field that records the concrete model selected during admission.
    - `models` VideoModelCard[], required
      - `schema_version` 'video-interface.v1'
      - `model` string, required
      - `display_name` string, required
      - `owned_by` 'beatra'
      - `capability` 'text_to_video' | 'image_to_video' | 'reference_to_video' | 'frames_to_video' | 'video_edit' | 'video_extend', required
      - `status` 'available'
      - `controls` string[], required
      - `output_formats` string[], required
      - `skus` VideoSKUCard[], required
        - `resolution` string, required
        - `duration_seconds` integer, required
      - `defaults` VideoDefaultsCard, required
        - `resolution` string, required
        - `duration` integer, nullable, required
        - `aspect_ratio` string, nullable
        - `generate_audio` boolean, nullable
        - `watermark` boolean, nullable
        - `web_search` boolean, nullable
        - `return_last_frame` boolean, nullable
      - `aspect` VideoAspectCard, required
        - `mode` 'explicit_control' | 'source_derived' | 'upstream_fixed' | 'unsupported', required
        - `accepts_explicit_value` boolean, required
        - `supported_values` string[], required
        - `default` string, nullable, required
        - `source_role` string, nullable, required
      - `duration` VideoDurationCard, required
        - `mode` 'explicit_control' | 'source_derived' | 'final_duration' | 'upstream_fixed', required
        - `required` boolean, required
        - `explicit_override` boolean, required
        - `supports_auto` boolean
      - `prompt_required` boolean, required
      - `prompt_max_units` integer, required
      - `prompt_unit` 'characters' | 'happyhorse_weighted', required
      - `reference_kinds` string[], required
      - `reference_roles` string[], required
      - `max_references` integer, required
      - `reference_limits` VideoReferenceLimitsCard
        - `image` integer, required
        - `video` integer, required
        - `audio` integer, required
        - `video_total_seconds` string, nullable
        - `audio_total_seconds` string, nullable
        - `audio_requires_image_or_video` boolean
      - `input_combinations` array[]
        - string[]
      - `output_audio` VideoOutputAudioCard
        - `included` boolean, required
        - `channel_layout` 'stereo', nullable
        - `source` 'model_generated', nullable
      - `media` object, required
      - `pricing` VideoPricingOption[], required
        - `meter` 'input_video_second' | 'output_video_second', required
        - `unit` 'second'
        - `unit_price_credits` string, required
        - `scale` string, required
        - `resolution` string, required
        - `duration_seconds` integer[], required
        - `applicability` 'video_input_present' | 'always', required
        - `billable_quantity` VideoBillableQuantityCard, required
          - `basis` 'admitted_output_duration_seconds' | 'final_output_duration_seconds' | 'reference_video_seconds' | 'capped_reference_video_seconds' | 'source_video_seconds' | 'source_and_reference_video_seconds', required
          - `counted_inputs` string[], required
          - `aggregate_max_seconds` string, nullable
          - `per_video_cap_seconds_by_video_count` object, nullable
        - `estimate_formula` '(unit_price_credits * billable_quantity) / scale'
  - MusicCapabilityDetail
    - `capability` 'text_to_music' | 'reference_audio_to_music', required
    - `endpoint` string, required
    - `input_modality` string, required
    - `output_modality` 'audio'
    - `execution_mode` 'async'
    - `description` string, required
    - `status` 'available' | 'unavailable', required
    - `auto` MusicAutoSelectionCard, required
      - `request_dependent` false
      - `default_for_omitted_request` string, nullable, required
      - `candidate_order` string[], required
      - `persisted_selection_field` 'resolved_model'
    - `models` MusicModelCard[], required
      - `schema_version` 'music-interface.v1'
      - `model` string, required
      - `display_name` string, required
      - `owned_by` 'beatra'
      - `capability` 'text_to_music' | 'reference_audio_to_music', required
      - `status` 'available'
      - `controls` string[], required
      - `constraints` MusicConstraintsCard, required
        - `prompt_min_characters` integer, required
        - `prompt_max_characters` integer, required
        - `custom_prompt_max_characters` integer, nullable
        - `negative_tags_max_characters` integer, nullable: Maximum characters for model_options.suno.negative_tags when that control is supported.
        - `lyrics_min_characters` integer, required
        - `lyrics_max_characters` integer, required
        - `title_max_characters` integer, required
        - `instrumental_forbids_lyrics` true
        - `vocal_lyrics_requirement` 'required_or_optimizer' | 'required_in_custom_mode' | 'reference_audio_asr_or_supplied', required
        - `reference_audio` MusicReferenceAudioConstraints
          - `required` true
          - `minimum_seconds` integer, nullable
          - `maximum_seconds` integer, required
          - `maximum_bytes` integer, nullable
          - `mime_types` string[], required
          - `accepted_kinds` string[], required
      - `output_mime_type` 'audio/mpeg'
      - `output_cardinality` 'one_or_more_clips'
      - `pricing` MusicPricingCard, required
        - `unit_credits` string, required
        - `unit` 'task'
        - `billing_basis` 'successful_task'
  - AudioCapabilityDetail
    - `capability` 'text_to_speech' | 'voice_clone', required
    - `endpoint` string, required
    - `input_modality` string, required
    - `output_modality` 'audio' | 'voice', required
    - `execution_mode` 'async'
    - `description` string, required
    - `status` 'available' | 'unavailable', required
    - `auto` AudioAutoSelectionCard, required
      - `request_dependent` boolean, required
      - `selection_inputs` string[], required
      - `default_for_omitted_request` string, nullable, required
      - `candidate_order` string[], required
      - `persisted_selection_field` 'resolved_model'
    - `models` AudioModelCard[], required
      - `schema_version` 'audio-interface.v1'
      - `model` string, required
      - `display_name` string, required
      - `owned_by` 'beatra'
      - `capability` 'text_to_speech' | 'voice_clone', required
      - `status` 'available'
      - `controls` string[], required
      - `constraints` union, required
        - SpeechConstraintsCard
          - `input_max_characters` 50000
          - `supported_languages` string[], required
          - `formats` string[], required
          - `sample_rates` integer[], required
          - `speed` AudioNumberRange, required
            - `minimum` string, required
            - `maximum` string, required
            - `exclusive_minimum` boolean
          - `volume` AudioNumberRange, required
            - `minimum` string, required
            - `maximum` string, required
            - `exclusive_minimum` boolean
          - `pitch` AudioNumberRange, required
            - `minimum` string, required
            - `maximum` string, required
            - `exclusive_minimum` boolean
          - `emotions` string[], required
          - `billing_character_weights` SpeechCharacterWeights
            - `han_ideograph` 2
            - `other` 1
          - `minimum_billable_characters` 0
        - VoiceCloneConstraintsCard
          - `accepted_sample_kinds` string[], required
          - `sample_min_seconds` 10
          - `sample_max_seconds` 300
          - `sample_max_bytes` 20971520
          - `consent_attestation_required` true
          - `automatic_formal_activation` true
      - `pricing` AudioPricingCard, required
        - `meter` 'character' | 'task', required
        - `unit` 'character' | 'task', required
        - `unit_price_credits` string, required
        - `scale` string, required
        - `billing_basis` 'beatra_weighted_characters' | 'successful_activated_voice', required
        - `estimate_formula` '(unit_price_credits * billable_quantity) / scale'
  - UnderstandingCapabilityDetail
    - `schema_version` 'understanding-interface.v1'
    - `capability` 'image_to_text' | 'video_to_text', required
    - `endpoint` string, required
    - `input_modality` string, required
    - `output_modality` 'text'
    - `execution_mode` 'sync_long'
    - `description` string, required
    - `status` 'available' | 'unavailable', required
    - `auto` UnderstandingAutoSelectionCard, required
      - `request_dependent` true
      - `default_for_omitted_request` string, nullable, required
      - `candidate_order` string[], required
    - `models` UnderstandingModelCard[], required
      - `schema_version` 'understanding-interface.v1'
      - `model` string, required
      - `display_name` string, required
      - `owned_by` 'beatra'
      - `capability` 'image_to_text' | 'video_to_text', required
      - `status` 'available'
      - `controls` string[], required
      - `media` UnderstandingMediaConstraintsCard, required
        - `kind` 'image' | 'video', required
        - `accepted_kinds` string[], required
        - `min_items` 1
        - `max_items` integer, required
        - `max_bytes_each` integer, required
        - `max_duration_seconds` integer, nullable
        - `sampling_fps` integer, nullable
      - `detail` UnderstandingDetailCard, required
        - `default` 'default'
        - `values` string[]
        - `affects_price` false
      - `thinking` UnderstandingThinkingCard, required
        - `public_control` false
        - `mode` 'adaptive' | 'model_default', required
      - `pricing` UnderstandingPricingCard[], required
        - `meter` 'image_count' | 'input_video_second', required
        - `unit` 'image' | 'second', required
        - `unit_price_credits` string, required
        - `scale` string, required
        - `billing_basis` 'admitted_image_count' | 'ceil_admitted_input_video_seconds', required
        - `estimate_formula` '(unit_price_credits * billable_quantity) / scale'
  - VideoPromptEnhancementCapabilityDetail
    - `capability` 'video_prompt_enhancement'
    - `endpoint` string, required
    - `input_modality` string, required
    - `output_modality` 'text'
    - `execution_mode` 'async'
    - `description` string, required
    - `status` 'available' | 'unavailable', required
    - `auto` VideoPromptEnhancementAutoCard, required
      - `request_dependent` false
      - `model_input_ignored` true
      - `resolved_model` string, required
      - `persisted_selection_field` 'resolved_model'
    - `models` VideoPromptEnhancementModelCard[], required
      - `schema_version` 'video-prompt-enhancement.v1'
      - `model` string, required
      - `display_name` string, required
      - `owned_by` 'beatra'
      - `capability` 'video_prompt_enhancement'
      - `status` 'available'
      - `controls` string[], required
      - `duration_seconds` object, required
      - `aspect_ratios` string[], required
      - `max_references` integer
      - `reference_limits` VideoReferenceLimitsCard, required
        - `image` integer, required
        - `video` integer, required
        - `audio` integer, required
        - `video_total_seconds` string, nullable
        - `audio_total_seconds` string, nullable
        - `audio_requires_image_or_video` boolean
      - `billing_mode` 'postpaid'
      - `billing_basis` 'successful_provider_reported_tokens'
      - `pricing` VideoPromptPricingOption[], required
        - `meter` 'input_token' | 'output_token', required
        - `unit` 'token'
        - `unit_price_credits` string, required
        - `scale` string, required

## Other responses

- `404`: Not Found
- `422`: Validation Error

---

[API](https://skmtc.dev/beatra/apis/agent-service-api.md) · [All operations](https://skmtc.dev/beatra/apis/agent-service-api/llms.txt) · [OpenAPI document](https://skmtc.dev/beatra/apis/agent-service-api/revisions/58e440556498?raw)