Search Model Schemas and Pricing Before You Run a Task
Use it when model availability changes faster than an application release:
- Search by workload, modality, or keyword.
- Read the selected model's current schema and examples.
- Show pricing before paid execution.
- Cache the response and revalidate with its ETag.
Endpoints#
| Endpoint | Description |
|---|---|
GET /v1/catalog/models |
Search and paginate available models |
GET /v1/catalog/models/{model_id} |
Read one complete model capability |
GET /v1/catalog/categories |
List categories and model counts |
GET /v1/catalog/openapi.json |
Generate OpenAPI 3.1 from the current Catalog |
Search models#
curl "https://api.poyo.ai/v1/catalog/models?service_type=generate&category=image&q=flux&limit=25"| Parameter | Description |
|---|---|
service_type |
chat or generate |
category |
Model category such as image, video, or audio |
tags |
Repeatable required tags |
q |
Free-text match against model ID, title, description, and tags |
cursor |
Opaque cursor returned by the previous page |
limit |
Page size from 1 to 100 |
Treat
model_idas an opaque public identifier. Store it exactly as returned and do not derive supplier or routing information from its shape.
Read the capability fields#
Each model includes:
model_id,service_type,category, title, description, and tagsinput_schemaandoutput_schema- Examples and supported chat protocols
- Streaming, callback, and execution-mode flags
- Public credit pricing
- A stable MCP-compatible
tool_name
Cache responses safely#
Catalog responses include:
ETagX-PoYo-Schema-VersionCache-Control: public, max-age=60, stale-while-revalidate=300
Send If-None-Match to receive 304 Not Modified when the projection has not changed.
Only execute parameters allowed by the current
input_schema. Model contracts can evolve independently of CLI and MCP package releases.