CreateGenerationRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/creativefabrica/json-schema/creativefabrica-create-generation-request-schema.json",
  "title": "CreateGenerationRequest",
  "description": "A generation request. The `modality` field discriminates the variant:\nimage modalities take image options and files (flat for most models,\nrole-keyed where the catalog lists roles); video modalities take video\noptions and role-keyed files; audio modalities take audio options and\nrole-keyed reference media. Per-model option support is declared in\nthe catalog (`GET /v1/models/{model}` →\n`capabilities.<modality>.inputSchema`).\n",
  "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/CreateGenerationRequest",
  "oneOf": [
    {
      "$ref": "#/$defs/CreateImageGenerationRequest"
    },
    {
      "$ref": "#/$defs/CreateVideoGenerationRequest"
    },
    {
      "$ref": "#/$defs/CreateAudioGenerationRequest"
    },
    {
      "$ref": "#/$defs/CreateTextInputGenerationRequest"
    },
    {
      "$ref": "#/$defs/CreateImageInputGenerationRequest"
    },
    {
      "$ref": "#/$defs/CreateMediaToTextGenerationRequest"
    },
    {
      "$ref": "#/$defs/CreateMediaToImageGenerationRequest"
    }
  ],
  "$defs": {
    "AudioFileInput": {
      "type": "object",
      "description": "One role-keyed reference file. Provide **either** `url` (publicly\nreachable file — generation starts immediately) **or** `fileName` +\n`mimeType` + `fileSizeBytes` (a presigned upload URL is returned and the\ngeneration waits in `upload_pending`) — never both.\n",
      "required": [
        "role"
      ],
      "properties": {
        "role": {
          "type": "string",
          "description": "Role of this file: `referenceAudio` (a voice to imitate),\n`referenceImage` (an image driving the audio), or `sourceVideo` /\n`sourceAudio` (the media a tool processes). Which roles a model\naccepts — and their per-role limits and cross-role rules — are per\nmodel: `GET /v1/models/{model}` → `capabilities.mediaToAudio.files`.\n"
        },
        "alias": {
          "type": "string",
          "description": "Prompt placeholder name — required for `reference*` roles and must be\ncited in the prompt as `{{alias}}`.\n"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Publicly reachable URL of the file (URL mode)."
        },
        "fileName": {
          "type": "string",
          "description": "File name including extension (upload mode)."
        },
        "mimeType": {
          "type": "string",
          "description": "MIME type (upload mode). Accepted formats are per role and model —\ncheck the role's `acceptedFormats` in the catalog.\n"
        },
        "fileSizeBytes": {
          "type": "integer",
          "format": "int64",
          "description": "Exact file size in bytes. Required in upload mode; must be positive.\n"
        },
        "durationSeconds": {
          "type": "integer",
          "description": "Asserted duration of the file. Required when the model prices\ndynamically on input duration (e.g. `byteplus_audio_separation_v1`\nand `fal_veed_clean_audio_v1` bill by source length). A video source\nis cross-checked against the file.\n\nFor an audio source of `fal_veed_clean_audio_v1` — the model that\nmeasures durations server-side — an uploaded file is measured when\nthe upload completes and the charge settles down on the measurement;\na URL-sourced file must carry this declaration, is priced on it, and\nthe charge settles down on the length the vendor reports. Other\nduration-priced audio models are priced on the declaration as it\nstands. Per-role duration limits are in the catalog.\n"
        }
      }
    },
    "AudioGenerationOptions": {
      "type": "object",
      "description": "Options for audio generations (`textToAudio`, `mediaToAudio`). This is the\ncross-model vocabulary — every field is optional and only valid for models\nthat declare it. The authoritative per-model field list, allowed values and\ndefaults live in the catalog: `GET /v1/models/{model}` →\n`capabilities.<modality>.inputSchema`. Options a model does not declare are\nrejected with `validation_error`.\n",
      "properties": {
        "speaker": {
          "type": "string",
          "description": "Catalog voice to speak in. Voice ids come from the model's voice\ncatalog: read `capabilities.voiceCatalog` from\n`GET /v1/models/{model}`, then list that catalog's voices. An id is\nonly valid on the catalog it came from.\n"
        },
        "format": {
          "type": "string",
          "description": "Output container, e.g. `mp3`, `wav`, `ogg_opus`, `pcm`."
        },
        "sample_rate": {
          "type": "integer",
          "description": "Output sample rate in Hz, e.g. `24000`."
        },
        "speech_rate": {
          "type": "integer",
          "description": "Speaking-speed offset. `0` is the model default; positive is faster.\nNote this changes playback length only — duration-priced models bill a\nspeed-independent duration, so speeding audio up does not reduce cost.\n"
        },
        "pitch_rate": {
          "type": "integer",
          "description": "Pitch offset. `0` is the model default."
        },
        "loudness_rate": {
          "type": "integer",
          "description": "Loudness offset. `0` is the model default."
        }
      },
      "additionalProperties": true
    },
    "CreateAudioGenerationRequest": {
      "type": "object",
      "required": [
        "model",
        "modality",
        "prompt"
      ],
      "properties": {
        "modality": {
          "type": "string",
          "enum": [
            "textToAudio",
            "mediaToAudio"
          ],
          "description": "`textToAudio` takes no files; `mediaToAudio` requires role-keyed reference media."
        },
        "model": {
          "type": "string",
          "description": "Model name from the catalog (`GET /v1/models`)."
        },
        "prompt": {
          "type": "string",
          "description": "The generation prompt. For speech models this is the text to speak,\nbut it is an instruction rather than a literal script — asking for\n\"a two-minute drama\" produces two minutes of audio. Where a model\ndeclares the complete script in `options`, as multi-voice speech\ndoes, this remains the request's descriptive prompt. Every\n`reference*` file's `alias` must be cited as `{{alias}}` and vice\nversa.\n"
        },
        "options": {
          "$ref": "#/$defs/AudioGenerationOptions"
        },
        "files": {
          "type": "array",
          "description": "Role-keyed reference media — required for `mediaToAudio`, forbidden\nfor `textToAudio`. Valid roles, per-role limits and cross-role rules\nare per model: `GET /v1/models/{model}` →\n`capabilities.mediaToAudio.files`.\n",
          "items": {
            "$ref": "#/$defs/AudioFileInput"
          }
        },
        "metadata": {
          "$ref": "#/$defs/Metadata"
        }
      }
    },
    "CreateImageGenerationRequest": {
      "type": "object",
      "required": [
        "model",
        "modality",
        "prompt"
      ],
      "properties": {
        "modality": {
          "type": "string",
          "enum": [
            "textToImage",
            "imageToImage"
          ],
          "description": "`textToImage` takes no files; `imageToImage` requires at least one input image."
        },
        "model": {
          "type": "string",
          "description": "Model name from the catalog (`GET /v1/models`)."
        },
        "prompt": {
          "type": "string",
          "description": "The generation prompt."
        },
        "options": {
          "$ref": "#/$defs/ImageGenerationOptions"
        },
        "files": {
          "type": "array",
          "description": "Input images — required for `imageToImage`, forbidden for\n`textToImage`. Accepted formats, file count and size limits are per\nmodel: `GET /v1/models/{model}` → `capabilities.imageToImage.files`.\nModels that list `roles` there are role-keyed: each file must set\nits `role`.\n",
          "items": {
            "$ref": "#/$defs/ImageFileInput"
          }
        },
        "metadata": {
          "$ref": "#/$defs/Metadata"
        }
      }
    },
    "CreateImageInputGenerationRequest": {
      "type": "object",
      "required": [
        "model",
        "modality",
        "prompt",
        "files"
      ],
      "properties": {
        "modality": {
          "type": "string",
          "enum": [
            "imageToText",
            "imageTo3D"
          ],
          "description": "An image-input analysis or 3D generation modality."
        },
        "model": {
          "type": "string",
          "description": "Model name from the catalog (`GET /v1/models`)."
        },
        "prompt": {
          "type": "string",
          "description": "The generation or analysis prompt."
        },
        "options": {
          "$ref": "#/$defs/GenericGenerationOptions"
        },
        "files": {
          "type": "array",
          "minItems": 1,
          "description": "Input images. Accepted formats, counts and size limits are published\nunder the selected model's modality capability.\n",
          "items": {
            "$ref": "#/$defs/ImageFileInput"
          }
        },
        "responseJsonSchema": {
          "type": "object",
          "description": "Optional JSON Schema for structured `imageToText` output. Rejected\nfor `imageTo3D`.\n",
          "additionalProperties": true
        },
        "metadata": {
          "$ref": "#/$defs/Metadata"
        }
      }
    },
    "CreateMediaToImageGenerationRequest": {
      "type": "object",
      "required": [
        "model",
        "modality",
        "prompt",
        "files"
      ],
      "properties": {
        "modality": {
          "type": "string",
          "enum": [
            "mediaToImage"
          ]
        },
        "model": {
          "type": "string",
          "description": "Model name from the catalog (`GET /v1/models`)."
        },
        "prompt": {
          "type": "string",
          "description": "The generation prompt. Models that derive their stills purely from\nthe source media ignore it — the field stays required because the\nmodality is shared with models that do read it.\n"
        },
        "options": {
          "$ref": "#/$defs/GenericGenerationOptions"
        },
        "files": {
          "type": "array",
          "minItems": 1,
          "description": "Role-keyed input media the images are derived from (typically one\n`sourceVideo`). Valid roles and constraints are published at\n`capabilities.mediaToImage.files` for the selected model. One\nrequest may yield several images; each arrives as its own output.\n",
          "items": {
            "$ref": "#/$defs/VideoFileInput"
          }
        },
        "metadata": {
          "$ref": "#/$defs/Metadata"
        }
      }
    },
    "CreateMediaToTextGenerationRequest": {
      "type": "object",
      "required": [
        "model",
        "modality",
        "prompt",
        "files"
      ],
      "properties": {
        "modality": {
          "type": "string",
          "enum": [
            "mediaToText"
          ]
        },
        "model": {
          "type": "string",
          "description": "Model name from the catalog (`GET /v1/models`)."
        },
        "prompt": {
          "type": "string",
          "description": "The analysis prompt. Models that perform a fixed analysis ignore it and\nreturn their own output regardless — the field stays required because\nthe modality is shared with models that do read it.\n"
        },
        "options": {
          "$ref": "#/$defs/GenericGenerationOptions"
        },
        "files": {
          "type": "array",
          "minItems": 1,
          "description": "Role-keyed input media. Valid roles and constraints are published at\n`capabilities.mediaToText.files` for the selected model.\n",
          "items": {
            "$ref": "#/$defs/VideoFileInput"
          }
        },
        "responseJsonSchema": {
          "type": "object",
          "description": "Optional JSON Schema constraining the structured response.",
          "additionalProperties": true
        },
        "metadata": {
          "$ref": "#/$defs/Metadata"
        }
      }
    },
    "CreateTextInputGenerationRequest": {
      "type": "object",
      "required": [
        "model",
        "modality",
        "prompt"
      ],
      "properties": {
        "modality": {
          "type": "string",
          "enum": [
            "textTo3D",
            "textToText"
          ],
          "description": "A text-only input modality; input files are not accepted."
        },
        "model": {
          "type": "string",
          "description": "Model name from the catalog (`GET /v1/models`)."
        },
        "prompt": {
          "type": "string",
          "description": "The generation prompt."
        },
        "options": {
          "$ref": "#/$defs/GenericGenerationOptions"
        },
        "metadata": {
          "$ref": "#/$defs/Metadata"
        }
      }
    },
    "CreateVideoGenerationRequest": {
      "type": "object",
      "required": [
        "model",
        "modality",
        "prompt"
      ],
      "properties": {
        "modality": {
          "type": "string",
          "enum": [
            "textToVideo",
            "mediaToVideo"
          ],
          "description": "`textToVideo` takes no files; `mediaToVideo` requires role-keyed input media."
        },
        "model": {
          "type": "string",
          "description": "Model name from the catalog (`GET /v1/models`)."
        },
        "prompt": {
          "type": "string",
          "description": "The generation prompt. Every `reference*` file's `alias` must be\ncited as `{{alias}}` and vice versa; frame and source roles bind\nstructurally without citation.\n"
        },
        "options": {
          "$ref": "#/$defs/VideoGenerationOptions"
        },
        "files": {
          "type": "array",
          "description": "Role-keyed input media — required for `mediaToVideo`, forbidden for\n`textToVideo`. Valid roles, per-role limits and cross-role rules are\nper model: `GET /v1/models/{model}` → `capabilities.mediaToVideo.files`.\n",
          "items": {
            "$ref": "#/$defs/VideoFileInput"
          }
        },
        "metadata": {
          "$ref": "#/$defs/Metadata"
        }
      }
    },
    "GenericGenerationOptions": {
      "type": "object",
      "description": "Model-specific generation options for audio, text/analysis and 3D\nmodalities. The authoritative fields, types, allowed values and defaults\nare published by `GET /v1/models/{model}` under\n`capabilities.<modality>.inputSchema`; undeclared fields are rejected.\n",
      "additionalProperties": true
    },
    "ImageFileInput": {
      "type": "object",
      "description": "One input image. Provide **either** `url` (publicly reachable file —\ngeneration starts immediately) **or** `fileName` + `mimeType` +\n`fileSizeBytes` (a presigned upload URL is returned and the generation\nwaits in `upload_pending`) — never both.\n",
      "properties": {
        "role": {
          "type": "string",
          "description": "Role of this file — required for role-keyed image models (the\ncatalog lists their roles under\n`capabilities.imageToImage.files.roles`, e.g. `sourceImage` for\n`recraft_v3_outpaint` or `referenceImage` for `kling_v3_omni_image`),\nomitted for flat-constraint models (the majority, which take\npositional files).\n"
        },
        "alias": {
          "type": "string",
          "description": "Prompt placeholder name — required for `referenceImage` (the catalog\nmarks it `aliasRequired`) and must be cited in the prompt as\n`{{alias}}`. Never set for `sourceImage`.\n"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Publicly reachable URL of the image (URL mode)."
        },
        "fileName": {
          "type": "string",
          "description": "File name including extension (upload mode)."
        },
        "mimeType": {
          "type": "string",
          "description": "MIME type (upload mode). Accepted formats are per model — check the\nmodel's `files.acceptedFormats` in the catalog.\n"
        },
        "fileSizeBytes": {
          "type": "integer",
          "format": "int64",
          "description": "Exact file size in bytes. Required in upload mode; must be positive.\n"
        }
      }
    },
    "ImageGenerationOptions": {
      "type": "object",
      "description": "Options for image generations (`textToImage`, `imageToImage`). This is\nthe cross-model vocabulary — every field is optional and only valid for\nmodels that declare it. The authoritative per-model field list, allowed\nvalues and defaults live in the catalog:\n`GET /v1/models/{model}` → `capabilities.<modality>.inputSchema`.\nOptions a model does not declare are rejected with `validation_error`.\n",
      "properties": {
        "outputCount": {
          "type": "integer",
          "minimum": 1,
          "description": "How many outputs to generate in one request. Only valid for models\nwhose `inputSchema` declares it — no current model does, so sending\nit is rejected with `validation_error` until a model adds support.\n"
        },
        "aspectRatio": {
          "type": "string",
          "description": "Image aspect ratio, e.g. `1:1`, `16:9`. Allowed values vary per\nmodel — check the model's `inputSchema`.\n",
          "x-go-name": "ImageAspectRatio"
        },
        "imageSize": {
          "type": "string",
          "description": "Image size tier, e.g. `1k`, `2k`, `4k`. Only for models whose\n`inputSchema` declares it.\n"
        }
      },
      "additionalProperties": true
    },
    "Metadata": {
      "type": "object",
      "description": "Opaque client key/value metadata, echoed back on reads.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "VideoFileInput": {
      "type": "object",
      "description": "One role-keyed input file. Provide **either** `url` (publicly reachable\nfile — generation starts immediately) **or** `fileName` + `mimeType` +\n`fileSizeBytes` (a presigned upload URL is returned and the generation\nwaits in `upload_pending`) — never both.\n",
      "required": [
        "role"
      ],
      "properties": {
        "role": {
          "type": "string",
          "description": "Role of this file: `firstFrame`, `lastFrame`, `referenceImage`,\n`referenceAudio`, `referenceVideo` or `sourceVideo`. Which roles a\nmodel accepts — and their per-role limits and cross-role rules —\nare per model: `GET /v1/models/{model}` →\n`capabilities.mediaToVideo.files`.\n"
        },
        "alias": {
          "type": "string",
          "description": "Prompt placeholder name — required for `reference*` roles (the\ncatalog marks them `aliasRequired`) and must be cited in the prompt\nas `{{alias}}`. Never set for frame or source roles.\n"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Publicly reachable URL of the file (URL mode)."
        },
        "fileName": {
          "type": "string",
          "description": "File name including extension (upload mode)."
        },
        "mimeType": {
          "type": "string",
          "description": "MIME type (upload mode). Accepted formats are per role and model —\ncheck the role's `acceptedFormats` in the catalog.\n"
        },
        "fileSizeBytes": {
          "type": "integer",
          "format": "int64",
          "description": "Exact file size in bytes. Required in upload mode; must be positive.\n"
        },
        "width": {
          "type": "integer",
          "description": "Asserted media width in pixels. Required when the model prices\ndynamically on input dimensions; cross-checked against the actual\nfile.\n"
        },
        "height": {
          "type": "integer",
          "description": "Asserted media height in pixels (see `width`)."
        },
        "durationSeconds": {
          "type": "integer",
          "description": "Asserted duration for audio/video inputs. Required when the model\nprices dynamically on input duration (e.g.\n`happy_horse_v1_video_editing` bills by source-video length);\ncross-checked against the actual file. Per-role duration limits are\nin the catalog.\n"
        },
        "fps": {
          "type": "integer",
          "description": "Asserted video frame rate rounded to the nearest integer (23.976 → 24,\n29.97 → 30). Required when the model prices on the source frame rate\n(the BytePlus enhance models with `fps` left at 0 = keep source);\ncross-checked against the actual file.\n"
        },
        "providerMetadata": {
          "type": "object",
          "description": "Per-file settings the model declares for this file's role, keyed by\nname: `GET /v1/models/{model}` →\n`capabilities.<modality>.files.roles.<role>.providerMetadata`. Each\nvalue is a plain JSON value of the declared type, validated against\nthat declaration; declared defaults are filled in for absent keys.\n",
          "additionalProperties": true
        }
      }
    },
    "VideoGenerationOptions": {
      "type": "object",
      "description": "Options for video generations (`textToVideo`, `mediaToVideo`). This is\nthe cross-model vocabulary — every field is optional and only valid for\nmodels that declare it. The authoritative per-model field list, allowed\nvalues and defaults live in the catalog:\n`GET /v1/models/{model}` → `capabilities.<modality>.inputSchema`.\nOptions a model does not declare are rejected with `validation_error`\n(e.g. `resolution` is not accepted by `kling_v3`, and\n`happy_horse_v1_video_editing` accepts neither `duration_seconds` nor\n`aspect_ratio`). Model-specific options outside this vocabulary (e.g.\n`audio_setting` on `happy_horse_v1_video_editing`) are passed as\nadditional properties, typed in the model's `inputSchema`.\n",
      "properties": {
        "duration_seconds": {
          "type": "integer",
          "description": "Requested video length in seconds. Range varies per model (e.g.\n4–15 on `seedance_v2`) and some models derive length from the\nsource media instead — check the model's `inputSchema`.\n"
        },
        "aspect_ratio": {
          "type": "string",
          "description": "Video aspect ratio, e.g. `16:9`, `9:16`. Allowed values vary per\nmodel and some models do not accept it — check the model's\n`inputSchema`.\n"
        },
        "resolution": {
          "type": "string",
          "description": "Output resolution, e.g. `720p`, `1080p`. Only for models whose\n`inputSchema` declares it.\n"
        },
        "mode": {
          "type": "string",
          "description": "Quality mode for models that tier their output (e.g. `kling_v3`:\n`std` / `pro` / `4k`). Only for models whose `inputSchema`\ndeclares it.\n"
        }
      },
      "additionalProperties": true
    }
  }
}