Models

GET /v1/models is the live contract for every model: operations, request schemas, accepted and returned media, and availability. It changes as models are added and retired, so read it at runtime rather than pinning a fixed list. A model’s id is publisher/model, which is also the path for POST /v1/run/{model_id}.

List models

curl https://api.protoface.com/v1/models \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"

Each object in data is one model’s contract.

Field	Meaning
`id`	Value for `POST /v1/run/{model_id}`
`owner`	Publisher, which is also the first half of the ID
`display_name` / `description`	Human-readable label and summary
`family`	Groups revisions of the same model
`aliases`	Other IDs that resolve to this model
`tags`	Free-form labels such as `video`, `generation`, `self-hosted`
`operations`	Each operation with its input roles and parameter names
`request_schemas`	JSON Schema per operation, where the model publishes one
`input_modalities` / `output_modalities`	Media accepted and returned
`execution_modes`	How the model runs
`execution_targets`	`shared`, or `dedicated` where capacity can be reserved
`pricing`	How the model meters, detailed under Metering
`available`	Whether the model is accepting runs
`revision` / `contract_revision`	Model version and contract version
`output_quality_descriptions`	Notes on quality tiers, where the model provides them

A model with available set to false rejects runs before any credits are reserved, returning error.code: "model.not_available".

Filter by what a model produces

Filter on output_modalities, whose values are video, image, audio, and model.3d.

curl -s https://api.protoface.com/v1/models \
  -H "Authorization: Bearer $PROTOFACE_API_KEY" \
  | jq -r '.data[] | select(.output_modalities | contains(["video"])) | .id'

A model that returns more than one kind of file matches more than one of these filters.

Retrieve one model

curl https://api.protoface.com/v1/models/minimax/minimax-h3 \
  -H "Authorization: Bearer $PROTOFACE_API_KEY"

Retrieving one model returns the same fields as its list entry. operations and request_schemas define the request.

Operations

operations is keyed by operation name. Each declares its media inputs as roles, its parameter names, and any dependencies between roles.

{
  "operations": {
    "video.general": {
      "required_input_roles": ["prompt"],
      "input_roles": {
        "prompt": { "types": ["text"], "modalities": ["text"] },
        "first_frame": { "types": ["asset"], "modalities": ["image"], "max_count": 1 },
        "last_frame": { "types": ["asset"], "modalities": ["image"], "max_count": 1 },
        "reference": { "types": ["asset"], "modalities": ["image"], "max_count": 9 }
      },
      "parameter_names": ["aspect_ratio", "duration_seconds", "generate_audio", "quality", "style"],
      "role_dependencies": { "last_frame": ["first_frame"] },
      "output_modalities": ["video"]
    }
  }
}

Violating role_dependencies returns error.code: "run.input_role_dependency". Here last_frame requires first_frame. A combination the model will not accept returns error.code: "run.input_role_conflict", naming the fields involved. A model with several operations requires operation on every request. Omitting it returns error.code: "run.operation_required" with the valid names.

Request schemas

request_schemas holds the JSON Schema for each operation, covering types, enums, defaults, and bounds. additionalProperties is false, so an unrecognized field is rejected rather than ignored.

{
  "request_schemas": {
    "video.general": {
      "type": "object",
      "additionalProperties": false,
      "required": ["prompt"],
      "properties": {
        "prompt": { "type": "string" },
        "duration_seconds": { "type": "integer", "minimum": 4, "maximum": 15, "default": 8 },
        "quality": { "type": "string", "enum": ["480p", "768p", "2k"], "default": "480p" },
        "first_frame": { "type": "string", "description": "A public URL, a data URI, or an asset id." }
      }
    }
  }
}

Bounds and enums are set per model, and a value outside them returns error.code: "run.parameter_invalid", naming the field.

Metering

pricing describes how a model meters, not what it charges. meter is output_seconds, which bills by the duration of the output, or request, which is a flat cost per call. Some duration-metered models also carry rounding and a duration_basis that says whether the meter counts the duration requested or the duration delivered. Request-metered models carry minimum_credits. Credits and limits covers what a run is actually charged.

Inference

Realtime

Account

Reference

List models

Filter by what a model produces

Retrieve one model

Operations

Request schemas

Metering

​List models

​Filter by what a model produces

​Retrieve one model

​Operations

​Request schemas

​Metering

List models

Filter by what a model produces

Retrieve one model

Operations

Request schemas

Metering