API Reference


Creates a new text file in Media Factory (filetype 4).

If a user ID is specified a check will be made to ensure the user exists, if the user doesn't this call will fail.

If a valid API KEY is supplied, the uid argument can be used to specify the user id. If this is not supplied, the file will be owned by the 'public' user. If no valid API KEY is supplied, a valid session token must be supplied. In this case the user-id will be determined based on the currently logged in user.

This is the function to use in order to post a comment on a media; please note that you have to specify the parentid to make the new text a comment on the pre-existing media.


int media.insertTextFile ( int vhost, array fileData )


NameTypeRequiredDefault valueDescription
vhostintRequirednoneThe vhost ID.
fileDataarrayRequirednoneA array with file information.


fileData is an array that consists of the information that you want to have stored in your media.

NameTypeDescriptionDefaultPossible Values
titleSTRINGThe title associated with the text media item.emptyempty / STRING
messageSTRINGThe media message to be included with the media item.emptySTRING
uidSTRINGThe UID of the user who created the media item.1INT
tagsSTRINGA space separated string containing words to be used as tags for the media item.emptyempty / STRING
filenameSTRINGA string that is going to be assigned as the original name of the file.emptyempty / STRING
extensionSTRING The extension that is going to be set as the original file extension of the text file.empty / STRINGpng,jpeg,mov
channelINTThe channel ID the media item is going to be uploaded into.emptyINT (channel ID)
dateYYYY-MM-DD HH:MM:SSThe date and time the media item started to be uploaded.emptyYYYY-MM-DD HH:MM:SS
injectorSTRINGA user-defined string, allows tracking where a file was inserted from.STRINGvideomixer, feedImporter2, httpupload, MediaFactory.com
urlSTRINGThe url reference.emptyempty
metadataARRAYAn ARRAY for any additional information that is to be stored with the media item. It is stored as an associated array in this field.

NB 1: You have to set the values of the metadata as an array which itself is a value of the 'users' array.

NB 2: When retrieving the information about the media using the API (via function Media.fileGetInfo), you do not specify the 'user' key: the data is returned as: metadata['synopsis'] = 'test1
empty array( 'user'=> Array ( 'synopsis' => 'test1', 'pin' => 'test2' ) )
moderationstatusINTThe initial moderation status of the media item once it is uploaded into MediaFactory.00,1,2,3,4 OR (unmoderated, accepted, denied, deleted, notdenied, moderated, all)
geo_latitudeNUMBERThe latitude of of where the media item was created. This is usually set in conjunction with Google Maps and the user plotting the pin on the map.empty62.86
geo_longitudeNUMBERThe latitude of of where the media item was created. This is usually set in conjunction with Google Maps and the user plotting the pin on the map.empty-52.44
parentidINT The media ID that is going to be assigned as the parent to this media item. This would be used in conjunction with context to create text comments.emptyINT
contextSTRINGThe type of media that is being uploaded.'generic''generic', 'all', 'comment', 'note', 'commentnote', 'genericcomment', 'parent','child'
languageSTRINGA 2-letter ISO code associated with the media.n/aSTRING
visibilitySTRINGThe visibility of the media item to the public once uploaded into MediaFactory.'VISIBLE''VISIBLE', 'HIDDEN'
groupidINT or ARRAYThe ID, or array of IDs, of the group that the media item is going to be uploaded into.

Note: To specify that the media item should _NOT_ be added to a group, set this value as 0.
externalidsARRAYThis is an array of the third party IDs for the file; it is available only if the file is hosted by one of our partners, such as Twitter, Instagram, Youtube, Brightcove, Widen and Ooyala.

The external id provider values are stored as an integer, and are below:
  • 0 - other: any provider other than the 7 mentioned below. You can store any reference using this provider.
    i.e. 'http://www.arbitrarysite.com/image=123'
  • 1 - Brightc ove
  • 2 - Youtube
  • 3 - Instagram
  • 4 - Twitter
  • 5 - Widen
  • 6 - Apple
  • 7 - Ooyala

*** NOTE 1 ***
Each recordset in the array is an array itself that contains the following:
    < li>external_id (string)
  • external_id_provider (integer)
  • created (the date the externalid record created/updated)
  • vhost
  • primary_external_id (Integer. States whether this is the media's primary external id: possible values: 1 or 0.)
  • .

    *** NOTE 2 *** Only one record can be the primary external id for each media.

    *** NOTE 3 *** The record that is noted as the primary external id is stored in the externalid with the reference to the external id provider stated b efore the external id.
empty Format

array (
   < ext. id provider 1 > => '< external id a >',
   < ext. id provider 2 > => '< external id b >'

Exam ple 1:
Updates media's external ids for Brightcove and Instagram.

   1 => '545433_57632'
   3 => '545433_57633'

Example 2:
Sets the `primary external i d` the media yo 2.
*** NOTE *** You can not set the `primary external id` to an externali id that does not exist for the media.

   1 => '545433_57632'
   3 => '545433_57633'


fileData is an array that consists of the information that you want to have stored in your media.

resultINTThe media ID of the newly created media item in MediaFactory.

Sample Response

Sample REST Response
<?xml version="1.0" encoding="UTF-8"?>
Sample JSON Response
    "status": true,
    "result": MEDIA_ID

Code examples


Be the first to comment on insertTextFile.

Add a Comment

  • captcha