POST statuses/update_with_media

Updated on Wed, 2012-04-18 10:50

Updates the authenticating user's status and attaches media for upload.

Unlike POST statuses/update, this method expects raw multipart data. Your POST request's Content-Type should be set to multipart/form-data with the media[] parameter

The Tweet text will be rewritten to include the media URL(s), which will reduce the number of characters allowed in the Tweet text. If the URL(s) cannot be appended without text truncation, the tweet will be rejected and this method will return an HTTP 403 error.

Important: Make sure that you're using upload.twitter.com as your host while posting statuses with media. It is strongly recommended to use SSL with this method.

Resource URL

https://upload.twitter.com/1/statuses/update_with_media.format

Parameters

status required

The text of your status update. URL encode as necessary. t.co link wrapping may affect character counts if the post contains URLs. You must additionally account for the characters_reserved_per_media per uploaded media, additionally accounting for space characters in between finalized URLs.

Note: Request the GET help/configuration endpoint to get the current characters_reserved_per_media and max_media_per_upload values.

media[] required

Up to max_media_per_upload files may be specified in the request, each named media[]. Supported image formats are PNG, JPG and GIF. Animated GIFs are not supported.

Note: Request the GET help/configuration endpoint to get the current max_media_per_upload and photo_size_limit values.

possibly_sensitive optional

Set to true for content which may not be suitable for every audience.

in_reply_to_status_id optional

The ID of an existing status that the update is in reply to.

Note: This parameter will be ignored unless the author of the tweet this parameter references is mentioned within the status text. Therefore, you must include @username, where username is the author of the referenced tweet, within the update.

lat optional

The latitude of the location this tweet refers to. This parameter will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding long parameter.

Example Values: 37.7821120598956

long optional

The longitude of the location this tweet refers to. The valid ranges for longitude is -180.0 to +180.0 (East is positive) inclusive. This parameter will be ignored if outside that range, not a number, geo_enabled is disabled, or if there not a corresponding lat parameter.

Example Values: -122.400612831116

place_id optional

A place in the world identified by a Twitter place ID. Place IDs can be retrieved from geo/reverse_geocode.

Example Values: df51dec6f4ee2b2c

display_coordinates optional

Whether or not to put a pin on the exact coordinates a tweet has been sent from.

Example Values: true

Extended description

Important: Make sure that you're using upload.twitter.com as your host while posting statuses with media. It is strongly recommended to use SSL with this method.

Users are limited to a specific daily media upload limit.. Requests to this endpoint will return the following headers with information regarding the user's current media upload limits:

  • X-MediaRateLimit-Limit - Indicates the total pieces of media the current user may upload before the time indicated in X-MediaRateLimit-Reset.
  • X-MediaRateLimit-Remaining - The remaining pieces of media the current user may upload before the time indicated in X-MediaRateLimit-Reset.
  • X-MediaRateLimit-Reset - A UTC-based timestamp (in seconds) indicating when X-MediaRateLimit-Remaining will reset to the value in X-MediaRateLimit-Limit and the user can resume uploading media.

If the user is over the daily media limit, this method will return an HTTP 403 error. In addition to media upload limits, the user is still limited in the number of statuses they can publish daily. If the user tries to exceed the number of updates allowed, this method will also return an HTTP 403 error, similar to POST statuses/update.

Example Request

POST

https://upload.twitter.com/1/statuses/update_with_media.json

POST Data

None

  1. {
  2.   "coordinates": null,
  3.   "created_at": "Thu Jun 02 18:53:19 +0000 2011",
  4.   "truncated": false,
  5.   "favorited": false,
  6.   "id_str": "76360760606986241",
  7.   "entities": {
  8.     "places": [
  9.  
  10.     ],
  11.     "urls": [
  12.  
  13.     ],
  14.     "media": [
  15.       {
  16.         "sizes": {
  17.           "large": {
  18.             "w": 700,
  19.             "resize": "fit",
  20.             "h": 466
  21.           },
  22.           "medium": {
  23.             "w": 600,
  24.             "resize": "fit",
  25.             "h": 399
  26.           },
  27.           "small": {
  28.             "w": 340,
  29.             "resize": "fit",
  30.             "h": 226
  31.           },
  32.           "thumb": {
  33.             "w": 150,
  34.             "resize": "crop",
  35.             "h": 150
  36.           }
  37.         },
  38.         "media_url_https": "https://p.twimg.com/AQ9JtQsCEAA7dEN.jpg",
  39.         "expanded_url": "http://twitter.com/twitter/status/76360760606986241/photo/1",
  40.         "id_str": "76360760611180544",
  41.         "url": "http://t.co/qbJx26r",
  42.         "id": 76360760611180544,
  43.         "type": "photo",
  44.         "indices": [
  45.           34,
  46.           53
  47.         ],
  48.         "display_url": "pic.twitter.com/qbJx26r",
  49.         "media_url": "http://p.twimg.com/AQ9JtQsCEAA7dEN.jpg"
  50.       }
  51.     ],
  52.     "hashtags": [
  53.       {
  54.         "text": "Photos",
  55.         "indices": [
  56.           0,
  57.           7
  58.         ]
  59.       }
  60.     ],
  61.     "user_mentions": [
  62.  
  63.     ]
  64.   },
  65.   "in_reply_to_user_id_str": null,
  66.   "contributors": null,
  67.   "annotations": null,
  68.   "text": "#Photos on Twitter: taking flight http://t.co/qbJx26r",
  69.   "retweet_count": "100+",
  70.   "id": 76360760606986241,
  71.   "in_reply_to_status_id_str": null,
  72.   "geo": null,
  73.   "retweeted": false,
  74.   "in_reply_to_user_id": null,
  75.   "place": null,
  76.   "source": "web",
  77.   "in_reply_to_screen_name": null,
  78.   "user": {
  79.     "profile_sidebar_border_color": "EEEEEE",
  80.     "expanded_url": null,
  81.     "profile_background_tile": false,
  82.     "profile_sidebar_fill_color": "F6F6F6",
  83.     "name": "Twitter",
  84.     "created_at": "Tue Feb 20 14:35:54 +0000 2007",
  85.     "location": "San Francisco, CA",
  86.     "profile_image_url": "http://a0.twimg.com/profile_images/1124040897/at-twitter_normal.png",
  87.     "id_str": "783214",
  88.     "profile_link_color": "038543",
  89.     "follow_request_sent": false,
  90.     "is_translator": false,
  91.     "entities": {
  92.       "urls": [
  93.  
  94.       ],
  95.       "hashtags": [
  96.  
  97.       ],
  98.       "user_mentions": [
  99.  
  100.       ]
  101.     },
  102.     "url": "http://twitter.com",
  103.     "default_profile": false,
  104.     "favourites_count": 10,
  105.     "contributors_enabled": true,
  106.     "id": 783214,
  107.     "utc_offset": -28800,
  108.     "profile_use_background_image": true,
  109.     "listed_count": 60735,
  110.     "antisocial": false,
  111.     "lang": "en",
  112.     "followers_count": 5345530,
  113.     "profile_text_color": "333333",
  114.     "protected": false,
  115.     "geo_enabled": true,
  116.     "time_zone": "Pacific Time (US & Canada)",
  117.     "description": "Always wondering what's happening. ",
  118.     "verified": true,
  119.     "profile_background_color": "ACDED6",
  120.     "notifications": false,
  121.     "display_url": null,
  122.     "friends_count": 556,
  123.     "statuses_count": 1127,
  124.     "default_profile_image": false,
  125.     "profile_background_image_url": "http://a1.twimg.com/images/themes/theme18/bg.gif",
  126.     "show_all_inline_media": true,
  127.     "screen_name": "twitter",
  128.     "following": true
  129.   },
  130.   "in_reply_to_status_id": null
  131. }