ModelCostResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/creativefabrica/json-schema/creativefabrica-model-cost-response-schema.json",
  "title": "ModelCostResponse",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/creativefabrica-idea-ai-genai-openapi.yml#/components/schemas/ModelCostResponse",
  "type": "object",
  "required": [
    "coinAmount",
    "pricing"
  ],
  "properties": {
    "coinAmount": {
      "type": "integer",
      "format": "int64",
      "description": "Coins charged for one generation with these inputs — read this field\nfor both pricing types.\n\nOn reserve-and-settle models this is not always the amount held and\nnever the final price: the generation reserves up front, settles to\nthe real cost on completion, and releases the difference. Two shapes\nexist today, and nothing in this response marks a model as one — see\nthe operation description before showing this figure to a user:\n\n- `seed_audio_1_0` is billed per second of generated audio, so this\n  is the maximum reserved.\n- `fal_veed_clean_audio_v1` (Clean Audio) settles on the input side.\n  For an uploaded audio file this is the amount held (the declared\n  duration plus rounding headroom). For a **URL-sourced** audio file\n  the run reserves the role maximum — **6,440 coins** (30 minutes) —\n  whatever was declared, and settles down onto fal's reported input\n  duration: this quote can be **below** the hold, so budget against\n  the reserved maximum there, not against this figure.\n"
    },
    "pricing": {
      "$ref": "#/$defs/Pricing"
    },
    "resolvedOptions": {
      "type": "object",
      "description": "The pricing-relevant option values the quote was computed from.\nSend exactly these values in the generation request to be charged\nexactly `coinAmount`. Absent for `standard`-priced models.\n\nThis guarantee does not extend to reserve-and-settle models — Seed\nAudio's charge depends on the output length, Clean Audio's on the\ninput length the vendor reports, and a URL-sourced Clean Audio run\nholds more than the quote — so no set of options pins the charge.\n",
      "additionalProperties": true
    }
  },
  "$defs": {
    "DynamicPricing": {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "dynamic"
          ],
          "description": "The coin amount is computed per request from the validated options\nand input media (e.g. video duration × resolution). Get the exact\namount up front via `POST /v1/models/{model}/cost`.\n"
        },
        "inputs": {
          "$ref": "#/$defs/PricingInputs"
        }
      }
    },
    "Pricing": {
      "description": "How the model is priced. `standard` pricing always carries `coinAmount`;\n`dynamic` pricing never does — the amount is computed per request (e.g.\nfrom duration, resolution and input media).\n",
      "oneOf": [
        {
          "$ref": "#/$defs/StandardPricing"
        },
        {
          "$ref": "#/$defs/DynamicPricing"
        }
      ]
    },
    "PricingInputs": {
      "type": "object",
      "description": "The inputs that determine this model's price — collect exactly these\nbefore calling `POST /v1/models/{model}/cost`. All of them are required\nthere; defaults are never applied. Empty/absent arrays mean the price\ndoesn't depend on that kind of input (both empty = flat-rate dynamic).\n",
      "properties": {
        "options": {
          "type": "array",
          "description": "`options` keys that affect the price.",
          "items": {
            "type": "string"
          }
        },
        "media": {
          "type": "array",
          "description": "Input-file roles whose metadata affects the price.",
          "items": {
            "$ref": "#/$defs/PricingMediaInput"
          }
        },
        "mediaAnyOf": {
          "type": "array",
          "description": "Roles, each listed as `optional` in `media`, of which at least one\nmust be supplied: the price reads whichever one is present. Absent\nwhen every priced role stands on its own.\n",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "PricingMediaInput": {
      "type": "object",
      "required": [
        "role",
        "requiredMetadata"
      ],
      "description": "Every file with this `role` must carry the listed metadata fields in the\ncost request's `inputMedia` (and as asserted metadata on the generation's\n`files`). Allowed file counts per role are in the role's catalog\nconstraints, not here.\n",
      "properties": {
        "role": {
          "type": "string"
        },
        "requiredMetadata": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "durationSeconds",
              "width",
              "height",
              "fps"
            ]
          }
        },
        "optional": {
          "type": "boolean",
          "description": "When true, the role itself is optional for pricing — a quote without\nany file of this role is valid (e.g. seedance_v2's referenceVideo).\nFiles that ARE supplied must still carry the `requiredMetadata`.\nAbsent/false means at least one file of this role is required to\nprice the model.\n"
        }
      }
    },
    "StandardPricing": {
      "type": "object",
      "required": [
        "type",
        "coinAmount"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "standard"
          ]
        },
        "coinAmount": {
          "type": "integer",
          "format": "int64",
          "description": "Coins charged per generation."
        }
      }
    }
  }
}