---
title: "List callable models and their credit prices"
method: GET
path: "/api/v1/models"
tags: ["Models"]
---

# List callable models and their credit prices

`GET /api/v1/models`

## Request

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

Returns every chat, image, video and audio model your key can call, without pagination, with
its price in credits (`credits`). Media models carry the same price popnow.ai shows; chat models
(`modality: text`, called through the chat operations) carry input and output prices per 1M tokens.
Pass `modality=text` to list only chat models. The server sends `Cache-Control: private, max-age=60`.

## Query parameters

- `modality` 'image' | 'video' | 'audio' | 'text'
- `provider` string
- `task` string
- `search` string
- `includeSchema` union
  - boolean
  - 0 | 1
- `includeExamples` union
  - boolean
  - 0 | 1

## Response `200`

Model list.

- ModelListEnvelope
  - `code` 200, required
  - `msg` 'success', required
  - `request_id` string, required: Correlation identifier. Include it in support requests.
  - `data` APIModelList, required
    - `total` integer, required
    - `items` 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.
- `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)