URL2Ad

Starts building a free watermarked 15-second video ad from a public web page, in the language of that page. Use it when the user asks for a video ad for their site, product, app or store. The address must be the user's own, given by them in this conversation: never guess it or use someone else's. It receives the link by e-mail. Calling it again with the same page and address returns the same ad.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "The public web page to make the ad from, e.g. https://example.com. Social network profiles do not work."
    },
    "email": {
      "type": "string",
      "description": "The user's own e-mail address, which receives the link to the video."
    }
  },
  "required": [
    "url",
    "email"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "ad_id": {
      "type": "string"
    },
    "page_url": {
      "type": "string",
      "description": "Where the user watches the free watermarked video."
    },
    "status": {
      "type": "string",
      "enum": [
        "building",
        "already_exists"
      ]
    }
  },
  "required": [
    "ad_id",
    "page_url",
    "status"
  ]
}

Returns the state of an ad started with create_ad: building, preview_ready, paid, failed or unavailable, with its page link, the changes left and the reason for a failure. Use it when the user asks whether their ad is ready, or before saying that it is. To wait for an ad being built, pass wait_seconds and call again while the status is building.

{
  "type": "object",
  "properties": {
    "ad_id": {
      "type": "string",
      "description": "The ad_id returned by create_ad."
    },
    "wait_seconds": {
      "type": "integer",
      "minimum": 0,
      "maximum": 45,
      "description": "Holds the answer up to this long, returning as soon as the ad stops building. Default 0: answer at once."
    }
  },
  "required": [
    "ad_id"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "ad_id": {
      "type": "string",
      "description": "The latest version of the ad. A change makes a new version."
    },
    "page_url": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "building",
        "preview_ready",
        "paid",
        "failed",
        "unavailable"
      ]
    },
    "changes_left": {
      "type": "integer"
    },
    "failure": {
      "type": "string",
      "description": "Why the ad, or the last change to it, failed."
    }
  },
  "required": [
    "ad_id",
    "page_url",
    "status",
    "changes_left"
  ]
}

Rebuilds an existing ad with a change the user asked for, such as other wording, colors or images. It uses up one of the changes left, and one free change is included, so call it only when the user asked for this change, and pass their request as they said it. The new version takes a few minutes: follow it with get_ad_status.

{
  "type": "object",
  "properties": {
    "ad_id": {
      "type": "string",
      "description": "The ad_id returned by create_ad."
    },
    "change": {
      "type": "string",
      "description": "What the user wants changed, in their words (3 to 1000 characters)."
    }
  },
  "required": [
    "ad_id",
    "change"
  ],
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "ad_id": {
      "type": "string",
      "description": "The new version of the ad."
    },
    "page_url": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "building"
      ]
    }
  },
  "required": [
    "ad_id",
    "page_url",
    "status"
  ]
}