Applications

An Application packages a tuned prompt, a chosen model, input requirements, and optional style presets behind one stable id like flatlay-to-model. Running one is a single call, and it returns a standard generation job you poll like any other.

Use Applications when you want a known-good result without picking a model or writing a prompt. Use Generations directly when you want full control.

The application object

Field	Type	Description
id	string	Stable slug. Pass to POST /v1/applications/:id/run.
kind	enum	image · video · audio — the medium it produces.
name	string	Human label, e.g. "Flatlay to Model".
description	string	One-sentence summary of what it does.
prompt	string	The base prompt. Your text is appended as additional guidance.
modelId	string	The model it runs on. Cost follows that model's pricing.
inputKind	enum	What the uploads are: image (default), video, or audio.
minImages	number	Minimum inputs required. 0 means text-only.
maxImages	number	Maximum inputs accepted.
acceptsText	boolean	Whether extra free-text guidance is allowed. Sending text when this is false is a 400.
categories	string[]	Merchandising verticals: film, marketing, social, education, art.
presets	object[]	Optional style presets: { id, name, prompt, thumb? }. Selecting one appends its prompt.
example	object	Optional before/after sample: { before, after, afterKind }. Paths are app-relative.
canvas	object	Optional custom run-screen hint for UI clients. Ignorable by API callers.

:::note inputKind decides which body field to use image applications take imageStorageIds (an array). video applications take videoStorageId, and audio applications take audioStorageId — both single ids, not arrays. :::

---

GET /v1/applications

List every Application whose underlying model is enabled.

Query parameters

Name	Type	Default	Description
limit	number	unset	Page size, 1–500. Omit for the full catalog (the gallery renders everything).
offset	number	0	Only meaningful with limit.

Returns { "applications": Application[], "collections": Collection[], "total": number } — total counts every served Application, not the page.

collections are curated merchandising shelves: { id, title, tagline, applicationIds } — shelf metadata over the whole catalog, returned in full regardless of pagination. Ignore them unless you're building a browsing UI.

Request

curl -s https://api.corte.so/v1/applications \
  -H "Authorization: Bearer corte_sk_…"

Response

{
  "applications": [
    {
      "id": "flatlay-to-model",
      "kind": "image",
      "name": "Flatlay to Model",
      "description": "Upload a flatlay of clothing or accessories and get a styled photo of a model wearing the items in a professional studio setting.",
      "prompt": "Given the products in the attached flatlay, generate an image of a model wearing the items in a professional photo studio setting. …",
      "modelId": "nano-banana-2",
      "minImages": 1,
      "maxImages": 1,
      "categories": ["marketing"],
      "acceptsText": true,
      "example": {
        "before": "/recipes/flatlay-to-model/before.jpg",
        "after": "/recipes/flatlay-to-model/after.jpg",
        "afterKind": "image"
      },
      "presets": [
        { "id": "studio-white", "name": "Studio White", "prompt": "Shot in a bright seamless white studio with soft, even lighting.", "thumb": "/recipes/flatlay-to-model/preset-studio-white.jpg" },
        { "id": "street-style", "name": "Street Style", "prompt": "Shot as candid street-style photography on a city sidewalk in natural daylight.", "thumb": "/recipes/flatlay-to-model/preset-street-style.jpg" }
      ]
    },
    {
      "id": "product-images",
      "kind": "image",
      "name": "Product Images",
      "description": "Describe your product and get professional imagery — perfect lighting, angles, and composition from a simple description.",
      "modelId": "seedream-5-lite",
      "minImages": 0,
      "maxImages": 0,
      "categories": ["marketing"],
      "acceptsText": true,
      "presets": ["…"]
    }
  ],
  "collections": [
    {
      "id": "advertising",
      "title": "Applications for Advertising",
      "tagline": "Create new ads in seconds — or remake the ones you already have. No production necessary.",
      "applicationIds": ["create-ad", "vary-ad", "ad-localization", "mockup", "product-reshoot", "product-video"]
    }
  ],
  "total": 43
}

---

POST /v1/applications/:id/run

Compose the Application's prompt with your inputs and submit a generation job.

Body

Name	Type	Required	Description
imageStorageIds	string[]	cond.	Committed image ids. Required for inputKind: "image" applications with minImages > 0. Count must be between minImages and maxImages.
videoStorageId	string	cond.	Single committed video id, for inputKind: "video".
audioStorageId	string	cond.	Single committed audio id, for inputKind: "audio".
text	string	cond.	Extra guidance, appended to the base prompt. Trimmed to 2,000 characters. Rejected when acceptsText is false. Required when the Application has no base prompt of its own.
presetId	string	no	A preset id from the Application's presets. Its prompt is appended too.
durationSeconds	number	cond.	Input media length. Required for duration-billed applications (video upscale, voice cleanup) so the estimate matches reality.
projectId	string	no	Bill the job to a shared project — the owner pays.

Returns { "job": GenerationJob, "estimatedCredits": number } — the same shape as POST /v1/generations. Poll GET /v1/generations/:id.

Request

curl -s -X POST https://api.corte.so/v1/applications/flatlay-to-model/run \
  -H "Authorization: Bearer corte_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "imageStorageIds": ["b0e7c9a1-4d52-4f0e-8c31-77a2e5d9f6b8"],
    "presetId": "street-style",
    "text": "Keep the jacket'\''s original colorway"
  }'

Response

{
  "job": {
    "id": "a91c2d7e-5f80-4c39-b6a2-13e7d0f4c885",
    "model": "nano-banana-2",
    "kind": "image",
    "status": "queued",
    "params": {
      "kind": "image",
      "prompt": "Given the products in the attached flatlay, … \n\nAdditional guidance from the user: Shot as candid street-style photography on a city sidewalk in natural daylight.\nKeep the jacket's original colorway",
      "aspectRatio": "16:9",
      "numImages": 1,
      "referenceStorageIds": ["b0e7c9a1-4d52-4f0e-8c31-77a2e5d9f6b8"]
    },
    "resultUrls": null,
    "resultStorageIds": null,
    "errorMessage": null,
    "costCredits": null,
    "createdAt": "2026-07-28T15:20:04.117Z",
    "completedAt": null,
    "projectId": "1b6d4f90-77c2-4a5e-b3d8-2e9a0c15f7b4",
    "cutId": null
  },
  "estimatedCredits": 12
}

The composed prompt in the response shows exactly what the model received: base prompt, then the preset prompt, then your text.

Errors

Code	When
not_found	Unknown Application id, or its model is currently disabled.
invalid_params	Too few or too many inputs, an unknown presetId, text on an Application that doesn't accept it, an uncommitted storageId, or no text on an Application that has no base prompt.
plan_required	The Application's model is paidOnly and the payer is on Free.
insufficient_credits · owner_insufficient_credits	Balance short. Nothing charged.

End-to-end

# 1. Get media in — one call from a URL
STORAGE_ID=$(curl -s -X POST https://api.corte.so/v1/uploads/import \
  -H "Authorization: Bearer $CORTE_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/flatlay.jpg"}' | jq -r .storageId)

# 2. Run the Application
JOB_ID=$(curl -s -X POST https://api.corte.so/v1/applications/flatlay-to-model/run \
  -H "Authorization: Bearer $CORTE_KEY" -H "Content-Type: application/json" \
  -d "{\"imageStorageIds\":[\"$STORAGE_ID\"],\"presetId\":\"studio-white\"}" | jq -r .job.id)

# 3. Poll until it settles
until [ "$(curl -s https://api.corte.so/v1/generations/$JOB_ID \
  -H "Authorization: Bearer $CORTE_KEY" | jq -r .job.status)" != "queued" ]; do sleep 3; done

curl -s https://api.corte.so/v1/generations/$JOB_ID \
  -H "Authorization: Bearer $CORTE_KEY" | jq -r '.job.resultUrls[]'