UGC Fans Studio

Lists the ad templates, ad features and creation modes UGC Fans offers, each with its slug, name and a sentence on what it makes. Free, and needs no sign-in. A template slug goes into ugcfans_make_ad as template; a feature slug as feature.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Words to look for in names and descriptions, such as \"testimonial\" or \"product video\". Leave out to list everything.",
      "maxLength": 200
    }
  },
  "required": [],
  "additionalProperties": false
}

Shows the signed-in account's credits left, credits granted and spent this period, when they expire, its plan and whether the account is admitted to UGC Fans. Free.

{
  "type": "object",
  "properties": {},
  "required": [],
  "additionalProperties": false
}

Opens a public web page in a sandboxed browser, records its text, pictures and layout, and returns a job whose result is a capture id. A capture is the raw material of ugcfans_make_launch_film and ugcfans_make_site_sting. Free of credits. Calling it confirms the person has the right to reuse the page's content in their own films. Only http and https pages on ports 80 and 443 can be captured.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The address of the page, starting with https:// or http://.",
      "maxLength": 2048
    },
    "viewport": {
      "type": "string",
      "description": "desktop captures a 1280 by 900 window (the default); phone captures 390 by 844 at twice the density.",
      "enum": [
        "desktop",
        "phone"
      ]
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}

Reads a finished capture: the address it ended on, the parts of the page that can go into a film (node_id, role and the first words), and whether a launch film can be made from it. Free.

{
  "type": "object",
  "properties": {
    "capture": {
      "type": "string",
      "description": "The capture id from the finished ugcfans_capture_website job.",
      "maxLength": 128
    }
  },
  "required": [
    "capture"
  ],
  "additionalProperties": false
}

Makes a 12-second launch film of the page's headline, button and picture from a finished capture, in the chosen frame, and returns a job. The result is an editable film; ugcfans_export_film renders it to MP4. Free of credits. A launch film has no text layers: its words are pictures of the page.

{
  "type": "object",
  "properties": {
    "capture": {
      "type": "string",
      "description": "The capture id.",
      "maxLength": 128
    },
    "aspect": {
      "type": "string",
      "description": "The frame: 16:9 landscape, 9:16 vertical, 1:1 square.",
      "enum": [
        "16:9",
        "9:16",
        "1:1"
      ]
    }
  },
  "required": [
    "capture",
    "aspect"
  ],
  "additionalProperties": false
}

Makes a 12-second, 8-scene film from the page parts you choose (node_ids from ugcfans_get_capture), in the chosen frame. Unlike a launch film its page text stays as editable text, so ugcfans_set_film_words can change it. Free of credits. Returns the film and its first revision at once.

{
  "type": "object",
  "properties": {
    "capture": {
      "type": "string",
      "description": "The capture id.",
      "maxLength": 128
    },
    "node_ids": {
      "type": "array",
      "description": "The node_id of each part to include, from ugcfans_get_capture.",
      "items": {
        "type": "string",
        "description": "A node_id.",
        "maxLength": 200
      },
      "minItems": 1,
      "maxItems": 100
    },
    "aspect": {
      "type": "string",
      "description": "The frame: 16:9 landscape, 9:16 vertical, 1:1 square.",
      "enum": [
        "16:9",
        "9:16",
        "1:1"
      ]
    },
    "key_phrase": {
      "type": "string",
      "description": "A phrase of the chosen text to feature. It must appear in the chosen parts.",
      "maxLength": 200
    }
  },
  "required": [
    "capture",
    "node_ids",
    "aspect"
  ],
  "additionalProperties": false
}

Makes an editable film from a finished video ad, so its captions and end card can be changed, and returns the film and its first revision. The ad must be finished, must not already be a film, must be a video and at most 96 MiB. Free of credits.

{
  "type": "object",
  "properties": {
    "ad": {
      "type": "string",
      "description": "The ad id, from a finished ugcfans_make_ad job.",
      "maxLength": 128
    }
  },
  "required": [
    "ad"
  ],
  "additionalProperties": false
}

Changes text in a film: every text layer whose words contain find gets replace, and the result is saved as a new revision; the earlier revision stays as it was. Films made by ugcfans_make_launch_film have no text layers, so nothing changes in them. Free of credits.

{
  "type": "object",
  "properties": {
    "film": {
      "type": "string",
      "description": "The film id.",
      "maxLength": 128
    },
    "revision": {
      "type": "string",
      "description": "The revision to edit.",
      "maxLength": 128
    },
    "replacements": {
      "type": "array",
      "description": "Pairs of words to find and what to put in their place, applied in order.",
      "items": {
        "type": "object",
        "properties": {
          "find": {
            "type": "string",
            "description": "The words to find.",
            "minLength": 1,
            "maxLength": 400
          },
          "replace": {
            "type": "string",
            "description": "The words to put in their place.",
            "maxLength": 400
          }
        },
        "required": [
          "find",
          "replace"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 20
    }
  },
  "required": [
    "film",
    "revision",
    "replacements"
  ],
  "additionalProperties": false
}

Renders one revision of a film to an MP4 with a content credential, and returns a job; when it is done the result carries a link to the file. Free of credits. A film with an unresolved rendering requirement cannot be exported.

{
  "type": "object",
  "properties": {
    "film": {
      "type": "string",
      "description": "The film id.",
      "maxLength": 128
    },
    "revision": {
      "type": "string",
      "description": "The revision to render.",
      "maxLength": 128
    }
  },
  "required": [
    "film",
    "revision"
  ],
  "additionalProperties": false
}

Runs up to 6 finishing operations in order on a clip of the library, each on the file the one before made: trim, reformat to another frame, burn in captions, overlay a brand logo, close with an end card, or mix in music. Returns the last job, whose result links the finished file. A call that runs past 4 minutes returns the job it is on and the operations still to run. Free of credits. The clip must already be in the library: upload footage at https://ugc.fans/library, then find its address with ugcfans_list_files. mix confirms the person may use the music file.

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "The clip's address in the library, out/...",
      "maxLength": 512
    },
    "operations": {
      "type": "array",
      "description": "The operations, in order.",
      "items": {
        "type": "object",
        "properties": {
          "op": {
            "type": "string",
            "description": "What to do.",
            "enum": [
              "trim",
              "reformat",
              "captions",
              "overlay",
              "end_card",
              "mix"
            ]
          },
          "start": {
            "type": "number",
            "description": "trim: where to start, in seconds (default 0).",
            "minimum": 0
          },
          "end": {
            "type": "number",
            "description": "trim: where to stop, in seconds.",
            "minimum": 0
          },
          "aspect_ratio": {
            "type": "string",
            "description": "reformat: the new frame.",
            "enum": [
              "9:16",
              "1:1",
              "16:9",
              "4:5"
            ]
          },
          "mode": {
            "type": "string",
            "description": "reformat: crop the picture, pad it, or follow the subject (default crop).",
            "enum": [
              "crop",
              "pad",
              "follow"
            ]
          },
          "transcript": {
            "type": "string",
            "description": "captions: the id of a transcript from ugcfans_transcribe.",
            "maxLength": 128
          },
          "cues": {
            "type": "array",
            "description": "captions: the lines to show, each with start and end seconds and its text.",
            "items": {
              "type": "object",
              "properties": {
                "start": {
                  "type": "number",
                  "description": "Seconds.",
                  "minimum": 0
                },
                "end": {
                  "type": "number",
                  "description": "Seconds.",
                  "minimum": 0
                },
                "text": {
                  "type": "string",
                  "description": "The line.",
                  "maxLength": 400
                }
              },
              "required": [
                "start",
                "end",
                "text"
              ],
              "additionalProperties": false
            },
            "maxItems": 2000
          },
          "brand": {
            "type": "string",
            "description": "overlay and end_card: the id of a saved brand; overlay puts its logo in the top-right corner, and end_card uses its colours and logo.",
            "maxLength": 128
          },
          "headline": {
            "type": "string",
            "description": "end_card: the closing headline.",
            "maxLength": 200
          },
          "subline": {
            "type": "string",
            "description": "end_card: a second line.",
            "maxLength": 200
          },
          "music": {
            "type": "string",
            "description": "mix: the address of the music file, out/..., which the person has the right to use.",
            "maxLength": 512
          }
        },
        "required": [
          "op"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 6
    }
  },
  "required": [
    "source",
    "operations"
  ],
  "additionalProperties": false
}

Writes out the words of an audio or video file in the library, up to 10 minutes long, with the built-in speech model, and returns a job; when it is done the result has the transcript id, its text, the language and the length. The transcript id feeds the captions operation of ugcfans_finish_clip. Free of credits. Upload footage at https://ugc.fans/library first, then find its address with ugcfans_list_files.

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "description": "The file's address in the library, out/...",
      "maxLength": 512
    }
  },
  "required": [
    "source"
  ],
  "additionalProperties": false
}

Lists files in the account's library, newest first: the path of each (out/...), its size and when it changed. Pictures, video, audio and fonts only. Free. Footage is added at https://ugc.fans/library; the path is what the clip and transcript tools take as source.

{
  "type": "object",
  "properties": {
    "prefix": {
      "type": "string",
      "description": "Only paths that start with this, such as out/api/images. The default is the whole library, out.",
      "maxLength": 512
    },
    "limit": {
      "type": "integer",
      "description": "How many files to list, newest first.",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [],
  "additionalProperties": false
}

Makes a link that opens one file of the library for anyone who holds it, without signing in. A link lasts 6 hours; a showcase page, which carries the Made with UGC Fans badge, lasts 30 days. Free. Anyone with the link can see the file until it expires.

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "The file's address in the library, out/...",
      "maxLength": 512
    },
    "kind": {
      "type": "string",
      "description": "link opens the file itself (default); showcase is a page that shows it.",
      "enum": [
        "link",
        "showcase"
      ]
    }
  },
  "required": [
    "path"
  ],
  "additionalProperties": false
}

Reads where a job stands: working, done with its files as links, failed with the reason, or cancelled. Free. Works for any job the account started.

{
  "type": "object",
  "properties": {
    "job": {
      "type": "string",
      "description": "The job id a tool returned, job_...",
      "maxLength": 128
    }
  },
  "required": [
    "job"
  ],
  "additionalProperties": false
}

Waits up to 45 seconds for a job to finish and reports where it stands, as ugcfans_get_job does. It returns as soon as the job ends. Free.

{
  "type": "object",
  "properties": {
    "job": {
      "type": "string",
      "description": "The job id a tool returned, job_...",
      "maxLength": 128
    },
    "seconds": {
      "type": "integer",
      "description": "How long to wait at most, up to 45 (default 45).",
      "minimum": 0,
      "maximum": 45
    }
  },
  "required": [
    "job"
  ],
  "additionalProperties": false
}

Stops a job that has not yet reached a provider; a cancelled job is not charged. A job that is already with a provider cannot be stopped and the call says so. Free.

{
  "type": "object",
  "properties": {
    "job": {
      "type": "string",
      "description": "The job id a tool returned, job_...",
      "maxLength": 128
    }
  },
  "required": [
    "job"
  ],
  "additionalProperties": false
}