Video.upload
From Facebook Developer Wiki
Contents |
Description
Uploads a video owned by the current session user and returns the new video. In order to upload a video from your application, the user must grant your application the video_upload extended permission.
Important: Upload requests must be formed as a MIME multi-part message sent using POST data. Each argument, including the raw video data, should be specified as a separate chunk of form data.
The details of preparing a MIME multi-part message depend on your particular request library, but typically the library allows you to specify POST, set various MIME headers, then add additional data. The resulting MIME message should look like the example request below. Note that all line breaks in the message should be a carriage return followed by a newline ('\r\n') rather than just a newline ('\n'). For example, after specifying each Content-Disposition line, you should print '\r\n\r\n'.
Where You Must Make this Call
Video uploads to Facebook happen on a specific set of servers. When you call video.upload, you need to account for this fact. You must make the video.upload call to http://api-video.facebook.com, and not api.facebook.com. If you call api.facebook.com, an error gets returned.
About User Upload Limits
Each user is subject to limits on the length and size of the video files they can upload, just like they are when uploading through Facebook. Use video.getUploadLimits to determine a specific user's limits. To increase video upload limits, users can verify their accounts with Facebook. One simple way to verify an account is by confirming a mobile phone number with Facebook. You can determine whether a user has verified their account querying for verified on the user FQL table or by calling users.isVerified, but in general you should determine a user's video limits independently with video.getUploadLimits. You might want to display these limits to the user before that user tries to upload a video to Facebook.
Supported Video Types
You can upload the following video file formats through this call:
- 3g2 (Mobile Video)
- 3gp (Mobile Video)
- 3gpp (Mobile Video)
- asf (Windows Media Video)
- avi (AVI Video)
- dat (MPEG Video)
- flv (Flash Video)
- m4v (MPEG-4 Video)
- mkv (Matroska Format)
- mod (MOD Video)
- mov (QuickTime Movie)
- mp4 (MPEG-4 Video)
- mpe (MPEG Video)
- mpeg (MPEG Video)
- mpeg4 (MPEG-4 Video)
- mpg (MPEG Video)
- nsv (Nullsoft Video)
- ogm (Ogg Format)
- ogv (Ogg Video Format)
- qt (QuickTime Movie)
- tod (TOD Video)
- vob (DVD Video)
- wmv (Windows Media Video)
Parameters
| Required | Name | Type | Description | |
| required | api_key | string | The application key associated with the calling application. If you specify the API key in your client, you don't need to pass it with every call. | |
|---|---|---|---|---|
| call_id | float | The request's sequence number. Each successive call for any session must use a sequence number greater than the last. We suggest using the current time in milliseconds, such as PHP's microtime(true) function. If you specify the call ID in your client, you don't need to pass it with every call. | ||
| sig | string | An MD5 hash of the current request and your secret key, as described in the How Facebook Authenticates Your Application. Facebook computes the signature for you automatically. | ||
| v | string | This must be set to 1.0 to use this version of the API. If you specify the version in your client, you don't need to pass it with every call. | ||
| [no name] | data | The file data for the video. | ||
| session_key | string | The session key of the user whose photo you are uploading. | ||
| optional | format | string | The desired response format, which can be either XML or JSON. (Default value is XML.) | |
| callback | string | Name of a function to call. This is primarily to enable cross-domain JavaScript requests using the <script> tag, sometimes known as "JSONP". This works with both XML and JSON. | ||
| title | string | The name of the video. The name cannot be longer than 65 characters. Longer titles will get truncated and will not return an error. | ||
| description | string | A description of the video. There is no limit to the length of the description. |
Example Requests
Example Return XML
Error Codes
| Code | Description | |
| 1 | An unknown error occurred. Please resubmit the request. | |
|---|---|---|
| 2 | The service is not available at this time. | |
| 101 | The API key submitted is not associated with any known application. | |
| 102 | The session key was improperly submitted or has reached its timeout. Direct the user to log in again to obtain another key. | |
| 103 | The submitted call_id was not greater than the previous call_id for this session. | |
| 104 | Incorrect signature. | |
| 200 | The application does not have permission to operate on the passed in uid parameter. | |
| 261 | Uploading videos requires the extended permission video_upload. | |
| 350 | Video file is too large. | |
| 351 | Video file was corrupt or invalid. | |
| 352 | Video file format is not supported. | |
| 353 | Missing or invalid video file. |
Notes
You can call this method using a session secret, and not the application secret (for example, for a Facebook Connect site or desktop application).
