Model Discovery and Selection — Piramyd API Reference

Piramyd’s model catalog changes as new models are added and updated. Never hardcode a model ID in your application — always call GET /v1/models at runtime to discover what is available, inspect capabilities, and select the right model for your workload. This ensures your integration stays current without any code changes on your end.

GET /v1/models

Returns the full list of models available to your API key, each with complete metadata.

GET /v1/models
Authorization: Bearer sk-YOUR_KEY

Example response

{
  "object": "list",
  "data": [
    {
      "id": "claude-opus-4.8",
      "name": "Claude Opus 4.8",
      "object": "model",
      "owned_by": "anthropic",
      "provider": "anthropic",
      "type": "chat",
      "tier": "pro",
      "endpoints": ["/v1/chat/completions", "/v1/responses"],
      "capabilities": ["text", "vision", "tool_use"],
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "context_length": 200000,
      "context_window": 200000,
      "max_output_tokens": 16384,
      "max_completion_tokens": 16384,
      "supports_tools": true,
      "supports_vision": true,
      "supports_reasoning": false,
      "description": "Anthropic's most capable model.",
      "visibility": "list"
    }
  ]
}

Response fields

string

required

The model identifier to use as the model parameter in inference requests. This is the canonical ID — use it exactly as returned.

string

Human-readable display name for the model. May differ from id.

string

Always "model" for entries in this list.

string

The organization that trained or owns the model (e.g. "anthropic", "openai").

string

The upstream provider Piramyd routes this model to. May differ from owned_by for multi-provider routing.

string

Model type. Currently "chat" for all inference models. System One models appear separately via GET /v1/systemone/models.

string

required

The subscription tier required to use this model. One of:

free — available on all plans including trial
pro — requires Solo ($30/mo) or higher
premium — requires Growth ( $50/mo) or Scale ($ 90/mo)

Check GET /v1/tiers for a full overview.

string[]

The API paths this model can be called on. Common values: "/v1/chat/completions", "/v1/responses", "/v1/messages". Only send a model to an endpoint listed here.

string[]

High-level capability tags such as "text", "vision", "tool_use". Mirrors the supports_* boolean fields.

string[]

The input types the model accepts: "text", "image", "audio", "video". Today’s catalog is primarily ["text"] or ["text", "image"].

string[]

The output types the model produces. Currently ["text"] for all chat models.

integer

Maximum number of input tokens the model accepts in a single request. Keep your prompt plus conversation history within this limit. Aliased as context_window — both fields are present and equal.

integer

Alias for context_length. Both fields are returned and always equal.

integer

Maximum tokens the model can generate in a single response. Use this to set a sensible upper bound for your max_tokens parameter. Aliased as max_completion_tokens.

integer

Alias for max_output_tokens, matching the OpenAI newer request parameter naming. Both fields are returned and always equal.

boolean

true if the model supports OpenAI-style function/tool calling. Always check this before sending tools in a request.

boolean

true if the model accepts image inputs via image_url content blocks. Note: this means the model can read images, not generate them.

boolean

true if the model supports extended chain-of-thought reasoning (e.g. thinking tokens).

string

A short human-readable description of the model’s strengths and intended use.

string

Controls whether the model appears in catalog listings. "list" means it appears in GET /v1/models responses.

GET /v1/models/{model_id}

Fetch metadata for a single model by its ID. Useful for validating a model ID your application has stored or received from user input.

GET /v1/models/claude-opus-4.8
Authorization: Bearer sk-YOUR_KEY

Returns the same object shape as a single entry in the data array above. The same normalization rules apply (see below).

Model ID Normalization

Piramyd accepts several ID formats for the same model. All of the following resolve to the same model:

Format	Example
Canonical ID	`claude-opus-4.8`
Case-insensitive	`Claude-Opus-4.8`
Provider-prefixed	`anthropic/claude-opus-4.8`
OpenRouter-style	`anthropic/claude-opus-4.8`

Use the canonical id from GET /v1/models in production — normalization is provided for convenience, not as a primary interface.

GET /v1/tiers

Returns an overview of which model tiers are available for your current subscription plan. Use this to understand which tier values (free, pro, premium) you can access before iterating the full model list.

GET /v1/tiers
Authorization: Bearer sk-YOUR_KEY

GET /v1/capabilities

Returns an API-level compatibility matrix for your integration. Use this to confirm which features are supported before relying on them in your application.

GET /v1/capabilities
Authorization: Bearer sk-YOUR_KEY

Example response

{
  "service": "piramyd-api",
  "api_version": "v1",
  "compatibility": {
    "chat_completions": true,
    "responses_compat": true,
    "responses_native_events": true,
    "legacy_completions": true,
    "moderations": false,
    "streaming_sse": true,
    "stream_include_usage": true,
    "max_completion_tokens": true,
    "request_id_header": true
  }
}

Note that moderations is false — the /v1/moderations endpoint is present for SDK compatibility but returns 501 not_implemented and should not be used for safety filtering.

Filtering Models Dynamically

Do not hardcode model IDs in your application. Model IDs, availability, and capabilities change as the catalog evolves. Applications that hardcode IDs will break silently when a model is updated or removed.

Always check supports_tools: true before including a tools array in your request. Sending tool definitions to a model that does not support them will return a 400 error.

The following example discovers all tool-capable models at runtime and selects one dynamically:

import httpx

BASE = "https://api.piramyd.cloud/v1"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

# Discover the full model catalog
response = httpx.get(f"{BASE}/models", headers=HEADERS)
models = response.json()["data"]

# Filter to chat models that support tool calling
tool_models = [
    m for m in models
    if "/v1/chat/completions" in m.get("endpoints", [])
    and m.get("supports_tools") is True
]

if not tool_models:
    raise RuntimeError("No tool-capable models available on your plan")

# Pick the first available tool-capable model
chosen = tool_models[0]
print(f"Using model: {chosen['id']}")
print(f"Context window: {chosen['context_length']} tokens")
print(f"Max output: {chosen['max_output_tokens']} tokens")

# Use it in a request
inference_response = httpx.post(
    f"{BASE}/chat/completions",
    headers=HEADERS,
    json={
        "model": chosen["id"],
        "messages": [{"role": "user", "content": "Hello!"}],
        "max_tokens": min(4096, chosen["max_output_tokens"]),
        "tools": [
            {
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "description": "Get current weather for a city",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "city": {"type": "string"}
                        },
                        "required": ["city"]
                    }
                }
            }
        ],
        "tool_choice": "auto",
    },
)
print(inference_response.json()["choices"][0]["message"])

Get Started

Core Concepts

Guides

Errors & Reliability

Model Discovery and Selection — Piramyd API Reference

GET /v1/models

Response fields

GET /v1/models/{model_id}

Model ID Normalization

GET /v1/tiers

GET /v1/capabilities

Filtering Models Dynamically

​GET /v1/models

​Response fields

​GET /v1/models/{model_id}

​Model ID Normalization

​GET /v1/tiers

​GET /v1/capabilities

​Filtering Models Dynamically

GET /v1/models

Response fields

GET /v1/models/{model_id}

Model ID Normalization

GET /v1/tiers

GET /v1/capabilities

Filtering Models Dynamically