Models

A model is one generation engine, addressed by a stable slug like kling-3 or nano-banana-2. Every model declares two things you need before you can call it: capabilities (what parameter values it accepts) and pricing (what it costs in credits).

Read the catalog rather than hardcoding: models are enabled and disabled without a deploy, and capability lists change as providers ship new versions.

The model object

Field	Type	Description
id	string	Stable slug. Pass this as model to POST /v1/generations.
kind	enum	video · image · audio · upscale. Must match params.kind.
displayName	string	Human label, e.g. "Kling 3.0".
provider	enum	fal · mock. Informational.
providerModelId	string	The upstream provider's own identifier. Informational.
paidOnly	boolean	true means the paying account must have bought something — a top-up or a plan; accounts that never have get plan_required (402).
enabled	boolean	Always true in responses — disabled models are filtered out.
pricing	object	See Pricing.
capabilities	object	Shape depends on kind. See Capabilities.

Pricing

Only the keys relevant to a model's billing basis are present.

Field	Type	Description
creditsPerSecond	map	Credits per output second, keyed by resolution. "*" is the fallback for every resolution.
creditsPerImage	map	Credits per image, keyed by "resolution|quality", quality, resolution, or "*".
creditsPerRun	number	Flat credits per job.
creditsPerThousandChars	number	Credits per 1,000 characters of input text (TTS).

100 credits = $1. To estimate a video job: creditsPerSecond["*"] × duration. You don't have to — POST /v1/generations returns estimatedCredits, and that's the number checked against your balance.

Capabilities

Capabilities are enforced server-side. Sending a value outside a declared list returns invalid_params (400) with the valid values in the message, before anything is charged.

kind: "video"

Field	Type	Description
durations	number[]	Allowed values for params.duration, in seconds.
resolutions	string[]	Allowed params.resolution, e.g. ["720p", "1080p"]. Optional.
aspectRatios	string[]	Allowed params.aspectRatio, listed widest to tallest.
supportsFirstFrame	boolean	Accepts startFrameStorageId.
supportsLastFrame	boolean	Accepts endFrameStorageId.
supportsAudioToggle	boolean	Honours generateAudio: false — returns a video-only file.
maxReferenceImages	number	Cap on referenceImageStorageIds. 0 means unsupported.
maxReferenceVideos	number	Cap on referenceVideoStorageIds.
maxReferenceAudios	number	Cap on referenceAudioStorageIds.
requiresSourceVideo	boolean	sourceVideoStorageId is mandatory (video-to-video, reframe, lip sync).
requiresReferenceImage	boolean	Needs startFrameStorageId or at least one referenceImageStorageIds.

kind: "image"

Field	Type	Description
aspectRatios	string[]	Allowed params.aspectRatio.
resolutions	string[]	Allowed params.resolution. Optional.
qualities	string[]	Allowed params.quality. Optional.
supportsImageReference	boolean	Accepts referenceStorageIds.
maxImages	number	Upper bound on params.numImages.

kind: "audio"

Field	Type	Description
category	enum	tts · music · sfx · cleanup · dubbing. Determines which params apply.
voices	string[]	Allowed params.voice for tts. Optional.
defaultVoice	string	Used when voice is omitted. Optional.
supportsLyrics	boolean	Accepts params.lyrics.
supportsInstrumental	boolean	Accepts params.instrumental.
supportsStyleInstructions	boolean	Accepts params.styleInstructions.
minSeconds / maxSeconds	number	Bounds on params.durationSeconds. Optional.
targetLanguages	string[]	Allowed params.targetLanguage for dubbing. Optional.

kind: "upscale"

Field	Type	Description
supportedTypes	string[]	Which inputs the upscaler accepts: "video", "image", or both.

---

GET /v1/models

List the models enabled for the account.

Query parameters

Name	Type	Default	Description
kind	string	—	Filter by kind: video, image, audio, or upscale — the same values as the model object's kind field. Any other value returns invalid_params (400).
limit	number	unset	Page size, 1–500. Omit for the full catalog (pickers render everything).
offset	number	0	Only meaningful with limit.

Returns { "models": Model[], "total": number } — total counts every model matching the filter, not the page.

Request

curl -s "https://api.corte.so/v1/models?kind=video" \
  -H "Authorization: Bearer corte_sk_…"

Response

{
  "models": [
    {
      "id": "kling-3",
      "kind": "video",
      "displayName": "Kling 3.0",
      "provider": "fal",
      "providerModelId": "fal-ai/kling-video/v3/standard/text-to-video",
      "paidOnly": false,
      "enabled": true,
      "pricing": {
        "creditsPerSecond": { "*": 17 }
      },
      "capabilities": {
        "kind": "video",
        "durations": [3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
        "resolutions": ["720p", "1080p"],
        "aspectRatios": ["16:9", "9:16", "1:1"],
        "supportsFirstFrame": true,
        "supportsLastFrame": false,
        "maxReferenceImages": 0,
        "maxReferenceVideos": 0,
        "maxReferenceAudios": 0,
        "requiresSourceVideo": false,
        "requiresReferenceImage": false
      }
    }
  ],
  "total": 16
}

An image model, for contrast:

{
  "id": "nano-banana-2",
  "kind": "image",
  "displayName": "Nano Banana 2",
  "provider": "fal",
  "providerModelId": "fal-ai/nano-banana-2",
  "paidOnly": false,
  "enabled": true,
  "pricing": { "creditsPerImage": { "*": 12 } },
  "capabilities": {
    "kind": "image",
    "aspectRatios": ["21:9", "16:9", "3:2", "4:3", "5:4", "1:1", "4:5", "3:4", "2:3", "9:16"],
    "supportsImageReference": true,
    "maxImages": 4
  }
}

:::note Pricing in examples The credit numbers above are illustrative. Real pricing is derived from live provider rates and moves when providers reprice — always read it from the catalog rather than copying it into your code. :::

Picking a model

Nothing in the API designates a default, and catalog order is storage order, not a ranking. Choose deliberately:

• Filter by kind for the medium you want.
• Filter out paidOnly: true if the paying account may be on Free.
• Check the capability you actually need — requiresSourceVideo for video-to-video, supportsImageReference for image-conditioned generation, maxReferenceImages > 0 for multi-reference work.
• Prefer 16:9 when the model offers it. aspectRatios[0] is a display accident — several models lead with 21:9, and taking the first entry silently opens them on ultrawide.

If you'd rather not choose at all, Applications bundle a model, a tuned prompt, and input requirements into a single id.