VidGenie API Documentation

vidgenie_api_docs.md

Authorization

There are 2 ways of sending the authorization credentials to a request on the Vidgenie API

URL Parameters

Send the user_email and user_token

Example: GET: "http://www.onvedeo.com/api/v1/[email protected]&user_token=1234"

Headers

Send the following headers

• X-User-Email
• X-User-Token

GET /api/v1/agent_qualities (authorization required)

Request parameters

• None

Success Response (200)

[
  {
    "id": 1,
    "name": "Communicator"
  },
  {
    "id": 2,
    "name": "Considerate"
  },
  {
    "id": 3,
    "name": "Knowledgeable"
  }
]

GET /api/v1/amenities (authorization required)

Request parameters

• None

Success Response (200)

[
  {
    "id": 1,
    "name": "Pool"
  },
  {
    "id": 2,
    "name": "Backyard"
  },
  {
    "id": 3,
    "name": "Deck"
  },
  {
    "id": 4,
    "name": "Dining Room"
  }
]

GET /api/v1/languages (authorization required)

Request parameters

• None

Success Response (200)

[
  {
    "id": 1,
    "name": "English",
    "short_name": "en"
  },
  {
    "id": 2,
    "name": "Spanish",
    "short_name": "es"
  }
]

GET /api/v1/property_types (authorization required)

Request parameters

• None

Success Response (200)

[
  {
    "id": 1,
    "name": "House"
  },
  {
    "id": 2,
    "name": "Apartment"
  }
]

GET /api/v1/songs (authorization required)

Request parameters

• None

Success Response (200)

[
  {
    "id": 1,
    "name": "Corporate Man",
    "category": "Epic",
    "url": "http://aws.com/epic-2.mp3"
  },
  {
    "id": 2,
    "name": "Bells and Whistles",
    "category": "Joyful",
    "url": "http://aws.com/joyful-3.mp3"
  }
]

GET /api/v1/themes (authorization required)

Request parameters

• None

Success Response (200)

[
  {
    "id": 1,
    "name": "Classic"
  },
  {
    "id": 2,
    "name": "Modern"
  }
]

POST /api/v1/vidgenie_videos (authorization required)

To generate a video, post a JSON request to the /api/v1/vidgenie_videos endpoint

Video Attributes

• song_name: (String) Required Any of the song names from the /songs endpoint
• theme_name: (String) Required Any of the theme names from the /themes endpoint
• language_names: (Array) Required An array of string with any of the language short names from the /languages endpoint
• callback_url: (String) Required A URL endpoint where a notification with the status of the video will be sent once the video generation is complete.
• reference: (JSON) Any valid JSON structure that will be returned on the notification callback. This field can be used to identify a particular property on your callback endpoint.

Property Attributes

• mls_id: (String)
• bathrooms: (Integer) Required
• bedrooms: (Integer) Required
• square_feet: (Integer) Required
• address: (String) Required
• city: (String) Required
• state: (String) Required
• country: (String) Required
• zip_code: (Integer) Required
• garage: (Integer)
• price: (Integer) Required
• rental: (Boolean)
• latitude: (Decimal)
• longitude: (Decimal)
• property_type: (String) Any of the property types from the /property_types endpoint
• landing_url: (String) Required A URL where the video will be publicly displayed (On the broker website). This is used to automatically generate a Video sitemap for the broker to receive the SEO benefits.

The latitude and longitude when provided will override the use of the address to identify the precise location of the property in order to display the map and find local videos.

Agent Attributes

• name: (String) Required Agent full name
• biography: (String) Any agent biography of description that will be shown on the video
• phone: (String) The agent phone number
• email: (String) Required The agent email
• photo_url: (String) A URL with a photo of the agent. Recommended image dimensions are minimum height of 300px and in a portrait format.
• custom_video_url: (String) A URL with a short custom message from the agent that will be used within the VidGenie video.
• qualities_tags: (Array) An array of agent qualities that are currently only used for the Agent focused Theme called "Star Agent". The qualities must be one of the available on the /agent_qualities endpoint
• license_id The agent's license number

Broker Attributes

• name: (String) Required Broker full name
• logo_url: (String) A URL with a logo the broker company.
• audio_intro_url: (String) A URL to a sound file (mp3, wav) to be used as a custom introduction message
• license_id The broker's license number

Property Assets Attributes An array of elements each with the following attributes:

• url: (String) Required A URL to a image of the property
• tags: (Array) Highly recommended. An array of strings used to display the photos in appropriate places within the VidGenie video.

Request body

{
  video: {
    song_name: "epic", 
    theme_name: "Classic",
    language_names: ["en", "es"],
    callback_url: "http://www.example.com/videos/1/callback",
    reference: {anything: "some_value"}
  },
  property: {
    bathrooms: 1,
    bedrooms: 1,
    square_feet: 200,
    address: "1000 Market St",
    city: "San Francisco",
    state: "CA",
    country: "US",
    zip_code: "94103",
    garage: 1,
    price: 1000000,
    rental: false,
    latitude: ...,
    longitude: ...,
    property_type: "House",
    landing_url: "http://www.realty5.com/properties/1000-market-st"
  },
  agent: {
    name: "Peter Rose",
    biography: "...",
    phone: "4152224444",
    email: "[email protected]",
    photo_url: "http://aws.com/agent.png",
    custom_video_url: "http://aws.com/agent.mp4",
    qualities_tags: ["communicator", "considerate"],
    license_id: "BRE12345"
  },
  broker: {
    name: "Realty 5",
    logo_url: "http://aws.com/logo.png",
    audio_intro_url: "http://aws.com/intro.wav",
    license_id: "SOMEID124"
  },
  property_assets: [
    {url: "http://aws.com/image1.jpg", tags: ["bathroom"]},
    {url: "http://aws.com/image2.jpg", tags: ["pool"]}
  ]
}

GET /api/v1/vidgenie_videos/:id (authorization required)

Request parameters

• id: Integer (The parameter is part of the URL)

Success Response (200)

{
  video: {
    id: 1,
    song_id: 1,
    theme_id: 1,
    status: "uploaded",
    embed_url: "http://www.onvedeo.com/properties/100-mission-st/embed",
    translations: [
      id: 1,
      default: true,
      processed: false,
      language: "English",
      sd_video_url: "http://www.aws.com/videos/1/sd_movie.mp4",
      hd_video_url: "http://www.aws.com/videos/1/movie.mp4"
    ]
    callback_url: "http://www.example.com/videos/1/callback",
    reference: {anything: "some_value"},
  }
}

GET Callback Request

Once the VidGenie video has been generated a notification will be sent to the callback url provided, with information about the video.

Request body

The request body will be exactly the same as the response from the /api/v1/vidgenie_videos/:id endpoint