---
title: "Model detail with typed media interface cards"
method: GET
path: "/v1/catalog/models/{model}"
tags: ["catalog"]
---

# Model detail with typed media interface cards

`GET /v1/catalog/models/{model}`

## 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/models/{model}`
- Auth: none declared

## Path parameters

- `model` string, required

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- union
  - ModelDetail
    - `model` string, required
    - `display_name` string, required
    - `owned_by` 'beatra'
    - `description` string, required
    - `status` 'available' | 'unavailable'
    - `interfaces` 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
  - VideoModelDetail
    - `model` string, required
    - `display_name` string, required
    - `owned_by` 'beatra'
    - `description` string, required
    - `status` 'available' | 'unavailable', required
    - `interfaces` union[], required
      - union
        - VideoModelCard
          - `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
              - …
            - `estimate_formula` '(unit_price_credits * billable_quantity) / scale'
        - VideoPromptEnhancementModelCard
          - `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
  - MusicModelDetail
    - `model` string, required
    - `display_name` string, required
    - `owned_by` 'beatra'
    - `description` string, required
    - `status` 'available' | 'unavailable', required
    - `interfaces` 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'
  - AudioModelDetail
    - `model` string, required
    - `display_name` string, required
    - `owned_by` 'beatra'
    - `description` string, required
    - `status` 'available' | 'unavailable', required
    - `interfaces` 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'
  - UnderstandingModelDetail
    - `model` string, required
    - `display_name` string, required
    - `owned_by` 'beatra'
    - `description` string, required
    - `status` 'available' | 'unavailable', required
    - `interfaces` 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'

## 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)