venice_ai.resources.models

Venice AI Models Resource Module.

This module provides comprehensive access to Venice AI's model ecosystem, enabling developers to discover available AI models, understand their capabilities, and efficiently select appropriate models for various tasks. The module supports model discovery through multiple approaches including direct listing, semantic traits, and compatibility mappings.

The Venice AI platform offers a diverse range of models optimized for different use cases including text generation, image generation, embeddings, text-to-speech, and image upscaling. This module provides the tools to navigate this ecosystem and make informed model selection decisions.

Key Features: - Comprehensive model discovery and listing - Semantic trait-based model selection (e.g., "fastest", "best", "default") - Cross-platform compatibility mappings for migration from other AI services - Model capability and pricing information - Type-based filtering for specific model categories

Classes: Models: Asynchronous resource for model discovery and information retrieval

Models Objects

class Models(APIResource["VeniceClient"])

Asynchronous resource for comprehensive model discovery and capability analysis.

This class provides a complete interface for exploring Venice AI's model ecosystem, including direct model listing, semantic trait-based discovery, and compatibility mappings for seamless migration from other AI platforms. All operations support flexible filtering and return detailed model metadata.

The class enables developers to make informed model selection decisions by providing access to model capabilities, pricing information, performance characteristics, and compatibility details across the entire Venice AI model catalog.

Key Capabilities:

List all available models with detailed metadata
Discover models by semantic traits (fastest, best, default, etc.)
Access compatibility mappings for external model migration
Filter models by type (text, image, embedding, TTS, upscale)
Retrieve comprehensive model specifications and pricing

Arguments:

client - The Venice AI client instance for making authenticated API requests.

Example:

Model discovery and selection:

.. code-block:: python

async with VeniceClient() as client:

List all available models

models = await client.models.list()

Find models by type

text_models = await client.models.list(type="text") image_models = await client.models.list(type="image")

Use semantic traits for easy selection

traits = await client.models.list_traits(type="text") fastest_model = traits.data["fastest"] best_model = traits.data["best"]

Check compatibility for migration

compatibility = await client.models.list_compatibility() venice_equivalent = compatibility.data.get("gpt-4")

Models.list

async def list(*, type: ModelListType | None = None) -> ModelsListResponse

Lists available models asynchronously.

Asynchronously retrieves a list of AI models available through the Venice API. Models can optionally be filtered by type to narrow down results to specific categories such as text generation, image generation, or embedding models.

Arguments:

type: Filter for model type. Valid API values: "text", "image", "embedding", "tts", "asr", "music", "upscale", "inpaint", "video", "all", "code". The SDK also accepts "chat" as an alias for "text" to match the user-facing language used elsewhere (e.g. :py:meth:resolve(type="chat") <resolve>). If not provided, the SDK sends type="all" so the response is the union of every model type — the server's own default is text-only, which surprises callers who expect "no filter" to mean "everything". Pass type="text" (or the "chat" alias) explicitly to recover the text-only listing.

Raises:

venice_ai.exceptions.APIError: If an API error occurs during the request. Example: List every model (text + image + embedding + tts + asr + music + upscale + inpaint + video + code):

models = await client.models.list()
for model in models.data:
    print(f"Model ID: {model.id}, Name: {model.name}")

Filter models by type:

chat_models = await client.models.list(type="chat")  # alias for "text"
image_models = await client.models.list(type="image")

Returns:

A list of available models with their metadata, capabilities, and pricing information.

Models.list_traits

async def list_traits(*, type: str | None = None) -> ModelTraitsResponse

Lists model traits and their associated model IDs asynchronously.

Asynchronously retrieves a mapping of semantic trait names (e.g., "default", "fastest", "best") to their corresponding model IDs. Traits provide convenient shortcuts for selecting models based on desired characteristics rather than specific model identifiers, making it easier to choose appropriate models without needing to know exact model versions or IDs.

Arguments:

type: Optional filter for model type. Only traits for models of the specified type will be returned. Valid values include "asr", "embedding", "image", "music", "text", "tts", "upscale", "inpaint", and "video".

Raises:

venice_ai.exceptions.APIError: If an API error occurs during the request. Example: Get all model traits:

traits = await client.models.list_traits()
default_model = traits.data.get("default")
fastest_model = traits.data.get("fastest")

Get traits for specific model type:

text_traits = await client.models.list_traits(type="text")
print(f"Default text model: {text_traits.data['default']}")

Returns:

A mapping of trait names to their corresponding model IDs.

Models.list_compatibility

async def list_compatibility(*,
                             type: str | None = None
                             ) -> ModelCompatibilityResponse

Lists model compatibility mapping between external model names and Venice model IDs asynchronously.

Asynchronously retrieves a mapping that allows applications to reference external model identifiers (e.g., from other AI platforms like OpenAI) and have them automatically mapped to equivalent Venice models. This compatibility layer facilitates smoother transitions when migrating applications from other AI platforms to Venice.

Arguments:

type: Optional filter for model type. Only compatibility mappings for models of the specified type will be returned. Valid values include "asr", "embedding", "image", "music", "text", "tts", "upscale", "inpaint", and "video". Defaults to "text" per the API spec.

Raises:

venice_ai.exceptions.APIError: If an API error occurs during the request. Example: Get all compatibility mappings:

compatibility = await client.models.list_compatibility()
venice_model = compatibility.data.get("gpt-4")
print(f"GPT-4 maps to Venice model: {venice_model}")

Get compatibility for specific model type:

text_compat = await client.models.list_compatibility(type="text")
for external_name, venice_id in text_compat.data.items():
    print(f"{external_name} -> {venice_id}")

Returns:

A mapping of external model names to their equivalent Venice model IDs.

Models.get

async def get(model_id: str) -> ModelResponse

Fetch a single model entry by its id.

Resolves against a 30-second TTL cache of :meth:list so back-to-back get() / :meth:get_capabilities calls don't each round-trip the full catalog. The Venice API has no per-model GET endpoint today; this method abstracts the list-and-filter pattern users would otherwise hand-roll.

Arguments:

model_id: The id of the model to fetch (e.g., "llama-3.3-70b").

Raises:

ValueError: If no model with that id is found in the catalog.

Models.get_capabilities

async def get_capabilities(model_id: str) -> Capabilities

Return a typed :class:Capabilities view of model_id.

Polymorphic by model type — the result is one of

Arguments:

model_id: The id of the model to introspect.

Raises:

ValueError: If no model with that id is in the catalog.

Models.resolve

async def resolve(*,
                  type: Literal["chat", "embedding", "image", "video", "tts",
                                "asr", "inpaint", "music"] = "chat",
                  require_function_calling: bool = False,
                  require_vision: bool = False,
                  require_reasoning: bool = False,
                  require_code_optimization: bool = False,
                  require_response_schema: bool = False,
                  min_context_tokens: int | None = None,
                  require_private: bool = False,
                  exclude_beta: bool = True,
                  video_type: Literal["text-to-video", "image-to-video"]
                  | None = None,
                  require_audio: bool = False,
                  min_resolution: str | None = None,
                  min_duration: str | None = None,
                  preferred_models: builtins.list[str] | None = None,
                  exclude_models: builtins.list[str] | None = None) -> str

Resolve a single model ID based on type and capability requirements.

This is the unified entry point for model selection, replacing the multi-step create_model_selector() → selector.select_*() pattern.

Arguments:

type: Model category to resolve. Defaults to "chat".
require_function_calling: Only consider models with function calling support.
require_vision: Only consider models with vision/image input support.
require_reasoning: Only consider models with reasoning capabilities.
require_code_optimization: Only consider code-optimized models.
require_response_schema: Only consider models supporting structured output.
min_context_tokens: Minimum context window size.
require_private: Only consider privacy-first models.
exclude_beta: Exclude beta models (default True).
video_type: Filter video models by "text-to-video" or "image-to-video".
require_audio: Only consider video models with audio support.
min_resolution: Minimum video resolution (e.g. "720p").
min_duration: Minimum video duration (e.g. "5s").
preferred_models: Preferred model IDs in priority order.
exclude_models: Model IDs to exclude.

Raises:

ValueError: If no model matches the given criteria.

Returns:

The resolved model ID string.

Models.resolve_cheapest_video

async def resolve_cheapest_video(
        *,
        duration: str = "5s",
        video_type: Literal["text-to-video", "image-to-video"] | None = None,
        resolution: str | None = None,
        audio: bool | None = None,
        aspect_ratio: str | None = None,
        exclude_models: builtins.list[str] | None = None,
        exclude_beta: bool = True) -> CheapestVideoResult

Resolve the cheapest video model by quoting all candidates.

Issues one POST /video/quote per candidate model and returns the model with the lowest USD quote.

Arguments:

video_type: Filter by "text-to-video" or "image-to-video".

Returns:

A :class:CheapestVideoResult with the cheapest model, price, and all quotes.

Models.resolve_chat

async def resolve_chat(*,
                       require_function_calling: bool = False,
                       require_vision: bool = False,
                       require_reasoning: bool = False,
                       require_code_optimization: bool = False,
                       require_response_schema: bool = False,
                       min_context_tokens: int | None = None,
                       require_private: bool = False,
                       preferred_models: builtins.list[str] | None = None,
                       exclude_models: builtins.list[str] | None = None,
                       exclude_beta: bool = True) -> str

Shortcut for resolve(type="chat", ...).

Models.resolve_embedding

async def resolve_embedding(
        *,
        preferred_models: builtins.list[str] | None = None,
        exclude_models: builtins.list[str] | None = None) -> str

Shortcut for resolve(type="embedding", ...).

Models.resolve_image

async def resolve_image(
        *,
        preferred_models: builtins.list[str] | None = None,
        exclude_models: builtins.list[str] | None = None) -> str

Shortcut for resolve(type="image", ...).

Models.resolve_video

async def resolve_video(*,
                        video_type: Literal["text-to-video", "image-to-video"]
                        | None = None,
                        require_audio: bool = False,
                        min_resolution: str | None = None,
                        min_duration: str | None = None,
                        preferred_models: builtins.list[str] | None = None,
                        exclude_models: builtins.list[str] | None = None,
                        exclude_beta: bool = True) -> str

Shortcut for resolve(type="video", ...).

Arguments:

video_type: Optional filter — "text-to-video" or "image-to-video". Omit to consider any video model.
require_audio: Only consider video models with audio support.
min_resolution: Minimum video resolution (e.g. "720p").
min_duration: Minimum video duration (e.g. "5s").
preferred_models: Preferred model IDs in priority order.
exclude_models: Model IDs to exclude.
exclude_beta: Exclude beta models (default True).

Models.resolve_video_upscale

async def resolve_video_upscale(
        *,
        preferred_models: builtins.list[str] | None = None,
        exclude_models: builtins.list[str] | None = None) -> str

Pick a video-upscaling model dynamically.

models.list(type="upscale") returns the image upscaler, not video. Video upscalers are registered under type="video" with model_type="video" (rather than "text-to-video" / "image-to-video") and video_input=True. This shortcut filters for that combination and returns the first match — typically topaz-video-upscale.

Arguments:

preferred_models: Preferred model IDs in priority order. The first preferred id present in the candidate set wins.
exclude_models: Model IDs to exclude from selection.

Raises:

ValueError: If no video-upscaling model is available. Example:

async with VeniceClient() as client:
    model = await client.models.resolve_video_upscale()
    quote = await client.video.quote_upscale(
        model=model, source_url=url, scale="2x"
    )

Returns:

Selected video-upscaling model ID.

Models.resolve_tts

async def resolve_tts(*,
                      preferred_models: builtins.list[str] | None = None,
                      exclude_models: builtins.list[str] | None = None) -> str

Shortcut for resolve(type="tts", ...).

Models.resolve_asr

async def resolve_asr(*,
                      preferred_models: builtins.list[str] | None = None,
                      exclude_models: builtins.list[str] | None = None) -> str

Shortcut for resolve(type="asr", ...).

Models.resolve_inpaint

async def resolve_inpaint(
        *,
        preferred_models: builtins.list[str] | None = None,
        exclude_models: builtins.list[str] | None = None) -> str

Shortcut for resolve(type="inpaint", ...).

Models.resolve_music

async def resolve_music(
        *,
        preferred_models: builtins.list[str] | None = None,
        exclude_models: builtins.list[str] | None = None) -> str

Shortcut for resolve(type="music", ...).

Models Objects​

List all available models

Find models by type

Use semantic traits for easy selection

Check compatibility for migration

Models.list​

Models.list_traits​

Models.list_compatibility​

Models.get​

Models.get_capabilities​

Models.resolve​

Models.resolve_cheapest_video​

Models.resolve_chat​

Models.resolve_embedding​

Models.resolve_image​

Models.resolve_video​

Models.resolve_video_upscale​

Models.resolve_tts​

Models.resolve_asr​

Models.resolve_inpaint​

Models.resolve_music​

Models Objects

Models.list

Models.list_traits

Models.list_compatibility

Models.get

Models.get_capabilities

Models.resolve

Models.resolve_cheapest_video

Models.resolve_chat

Models.resolve_embedding

Models.resolve_image

Models.resolve_video

Models.resolve_video_upscale

Models.resolve_tts

Models.resolve_asr

Models.resolve_inpaint

Models.resolve_music