---
title: "Get one model, including its input JSON Schema"
method: GET
path: "/api/v1/models/{model}"
tags: ["Models"]
---

# Get one model, including its input JSON Schema

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

## Request

- Base URL: `https://api.popnow.ai`
- URL: `https://api.popnow.ai/api/v1/models/{model}`
- Auth: HTTP bearer

`model` is the exact value used by `createTask.model` and may contain
slashes. URL-encode embedded slashes when using clients that treat path
parameters as one segment (for example `family%2Fversion%2Ftask`).

## Path parameters

- `model` string, required

## Response `200`

Complete model record.

- ModelEnvelope
  - `code` 200, required
  - `msg` 'success', required
  - `request_id` string, required: Correlation identifier. Include it in support requests.
  - `data` APIModel, required
    - `model` string, required: Model call name in `<publisher>/<model>/<task>` form; the value `createTask.model` takes. Image editing uses the `edit` suffix.
    - `family` string, required: Stable product-family identifier; endpoint variants are listed in `tasks` and expressed by `inputSchema`.
    - `displayName` string, required
    - `provider` string, required: Model creator/author identifier, such as the research lab that built the model.
    - `modality` 'text' | 'image' | 'video' | 'audio', required
    - `tasks` string[], required: The internal task classification of this one endpoint. Always exactly one element, and it is not always the suffix of `model`: image editing endpoints are published as `.../edit` but classified as `image-to-image` (or `image-edit` for single-purpose tools). Use `model` to call, and `tasks[0]` only to group or filter. New values appear as models are added, so treat the set as open.
    - `async` boolean, required
    - `toolkit` 'subject-swap' | 'studio-tools': Which toolkit family this model belongs to (subject-swap for identity swaps; studio-tools for single-purpose image and video tools such as background removal or upscaling). Informational classification for catalogue grouping only; it does not participate in routing, pricing or authorization. Absent when the model is not part of a toolkit.
    - `taskTimeoutSeconds` integer, required: Absolute platform execution deadline before timeout/refund; not media output duration.
    - `maxOutputDurationSeconds` integer: Maximum output duration the model schema allows, taken from the `maximum` of its `duration_seconds` property; omitted when that property is absent or has no declared maximum. Distinct from `taskTimeoutSeconds`, which is the platform execution deadline.
    - `enabled` boolean, required
    - `available` boolean, required: Whether the model can be called right now.
    - `quantityField` string, required
    - `credits` object, required: Price in credits (1 credit = $0.001). Media models carry the same price popnow.ai shows: `unit` is how the price scales (`per_image`, `per_second`, `per_request`…), `perUnit` is the starting price per unit, and `rules` lists the tiers: each rule applies when the request matches its `when` values (`*` matches the field that sets the tier). Use jobs/quote for the exact amount of one request. Chat models have `unit: per_1m_tokens` and price `input`, `output` (and, where the model has them, `cachedInput`, `cacheWrite` and a `longContext` tier that applies to the whole request once its input exceeds `thresholdTokens`) in credits per 1M tokens; a call is charged its actual usage in fractional credits.
      - `unit` string, required
      - `perUnit` number
      - `input` number: Chat models only. Credits per 1M input tokens.
      - `output` number: Chat models only. Credits per 1M output tokens (reasoning tokens count as output).
      - `cachedInput` number: Chat models only. Credits per 1M cached input tokens.
      - `cacheWrite` number: Chat models only. Credits per 1M tokens written to the prompt cache.
      - `longContext` object: Chat models only. Prices for requests whose input exceeds thresholdTokens (reaches it when inclusive is true).
        - `thresholdTokens` integer
        - `inclusive` boolean
        - `input` number
        - `cachedInput` number
        - `cacheWrite` number
        - `output` number
      - `rules` object[]
        - `when` object, required
        - `perUnit` number, required
        - `unit` string
    - `inputSchema` object: JSON Schema draft 2020-12 used by `createTask.input` validation and Playground rendering. Standard JSON Schema keywords validate. Presentation hints live only in a per-property `x-ui` object whose keys are snake_case and drawn from a closed set: `widget`, `order`, `label`, `placeholder`, `rows`, `step`, `unit`, `accept`, `max_size_mb`, `max_duration_seconds`, `max_total_duration_seconds`, `advanced`, `primary`, `affects_price`, `visible_when`, `enum_labels`, `reference_tokens`, `reference_sequence`, `reference_regions`, `mask`. `x-ui.order` is the only source of field order (descending first). `x-ui.widget` is one of `textarea`, `text`, `upload`, `multi-upload`, `select`, `radio`, `slider`, `number`, `switch`, `json`, `object-list`, `chat-messages`, `hidden`. Root-level composition is limited to `anyOf`, where every branch contains only `required`, and `allOf`, where each branch is `if` (`required` or `properties.*.const`) plus `then` (`required`); `oneOf`, `not` and `dependentSchemas` never appear. Unknown hints must be ignored.
    - `version` string, required: Public model-catalog version label used to detect schema or metadata changes.
    - `availability` 'planned' | 'available' | 'preview' | 'maintenance', required
    - `badges` string[], required: Closed capability and licensing vocabulary; clients should ignore unknown future IDs.
    - `relatedModels` string[], required: Curated model identifiers suitable for alternatives or workflow steps.
    - `examples` APIModelExample[]: A ready-to-run example input, the same one the API reference shows. Validated against this model's current input schema.
      - `id` string, required
      - `input` object, required
      - `sortWeight` integer, required
    - `updatedAt` string, date-time, required

## Other responses

- `400`: Invalid JSON, query, callback URL, model input, or media declaration. Invalid callBackUrl values return code 400 and msg "Invalid callback URL" with request_id. Submitted hosts, IP addresses, and DNS diagnostics are not echoed.
- `401`: Missing, malformed, expired, revoked, or otherwise invalid API key.
- `403`: Account, model, API-key, IP, or region authorization failed.
- `404`: Resource does not exist or is not visible to this account and API key. These cases are intentionally indistinguishable.
- `429`: Account-level request limit exceeded.
- `500`: Internal failure. Details are not exposed; report `request_id` to support.

---

[API](https://skmtc.dev/popnow/apis/popnow-api.md) · [All operations](https://skmtc.dev/popnow/apis/popnow-api/llms.txt) · [OpenAPI document](https://skmtc.dev/popnow/apis/popnow-api/revisions/ba5c069f11d8?raw)