Uploading

Because of the way XML works, you can't send binary data as part of an XML request.  Instead, you have to encode it using base64 encoding, which increases the size by 25%.  So SmugMug provides a variety of upload methods so you can select the best one for your particular application.  SmugMug recommends using the HTTP PUT or RAW HTTP POST methods, but that's entirely up to you.

HTTP PUT

The HTTP spec specifies a method for sending binary files via HTTP called PUT.  SmugMug supports HTTP PUT, and it's one of the two preferred methods because the data is entirely passed in binary form, which increases the speed over base64 encoding by 25%.

We'll return an XML formatted response as if you'd made a normal API request for the smugmug.images.upload method, based on the ResponseType given. 

The URL for the PUT request consists of both the server you're uploading to (upload.smugmug.com) and the filename of the file you're sending (photo.jpg). 

Example:  http://upload.smugmug.com/photo.jpg

Since the body of the message is purely the binary data of the image you're adding to SmugMug, you have to send some metadata, such as AlbumID, in the HTTP headers so we know what to do with it.  Here are the header fields supported by the HTTP PUT method:

• Content-Length
  • required
  • standard HTTP header, must match the actual bytes sent in the body (your image)
• Content-MD5
  • required
  • standard HTTP header, must be an MD5 of the data in the body (your image)
• X-Smug-SessionID
  • required
  • SessionID from API login calls
• X-Smug-Version
  • required
  • API Version (ex: 1.1.1)
• X-Smug-ResponseType
  • required
  • set "XML-RPC", "REST", "JSON" or "PHP" depending on your desired response formatting.
    
• X-Smug-AlbumID
  • required (for uploading new photos, not for replacing existing photos)
  • The AlbumID you're adding the photo to
• X-Smug-ImageID
  • required (for replacing existing photos, not for uploading new photos)
    
  • The ImageID of the photo you are replacing
• X-Smug-FileName
  • optional
  • The filename of the photo you're adding
    
• X-Smug-Caption
  • optional
  • Sets the Caption on the image
  • For multi-line captions, use a carriage return between lines
    
• X-Smug-Keywords
  • optional
  • Sets the Keywords on the image
• X-Smug-Latitude
  • optional
  • Sets the Latitude of the image (in the form D.d, such as 37.430096)
    
• X-Smug-Longitude
  • optional
  • Sets the Longitude of the image (in the form D.d, such as -122.152269)
    
• X-Smug-Altitude
  • optional
  • Sets the Altitude of the image (in meters)
    

RAW HTTP POST

POSTing raw data instead of encoded data is almost identicaly to HTTP PUT, above, except that it uses HTTP POST instead of HTTP PUT. 

RAW POST URL:  http://upload.smugmug.com/photos/xmlrawadd.mg

Instead of a typical multi-part form encoded POST, with the various necessary variables, including the image data, included in the body, the body only contains the raw binary image data and the rest of the metadata is contained in the headers, just like HTTP PUT.

MULTI-PART HTTP POST

You can also POST data using a standard multi-part encoded form request.  Include each variable as a value in the form data.

MULTI-PART POST URL:  http://upload.smugmug.com/photos/xmladd.mg

Just like the HTTP PUT and RAW HTTP POST methods, we'll return an XML formatted response just like if you'd called the smugmug.images.upload API method.

Multi-part binary requests include a "name" element and a "filename" element.  We're expecting a non-array for the "name" portion (name it anything you wish), and the full filename, with extension (no path!) for the "filename" portion.

Fields accepted by HTTP POST:

• ByteCount
  • required
  • must match the actual binary byte count of the image you're sending
• MD5Sum
  • required
  • must match the md5 value of the binary file you're sending
• AlbumID
  • required
  • The AlbumID you're adding this photo to
• ResponseType
  • required
  • either "XML-RPC", "REST", "JSON" or "PHP" depending on your desired response formatting.
• Caption
  • optional
  • Sets the Caption on the image

API UPLOADS

Finally, you can just use the normal XML-RPC and REST smugmug.images.upload calls.   Make sure you're using upload.smugmug.com as your endpoint hostname, rather than api.smugmug.com