">mixi Developer Center (mDC)

mixi Connect

mixi Connect (English) » mixi Graph API » Technical Specification » Photo API

Photo API

Photos are very important contents which enable users to enjoyably communicate within mixi. Photos are filled with the users' memories and emotions and many users want to post their photos and share them with their friends. With the Photo API, users can post photos on mixi as soon as they are taken.

The following describes how to use the Photo API.

Preparation

To use the Photo API, please acquire the following information beforehand:

  • • Access token approved for “r_photo” scope or ”w_photo” scope, or both scopes

Photo API cannot be accessed using other scopes not specified above. For instructions on how to acquire the access token, please refer to the authentication approval procedure.

Photo API capabilities and scopes

The Photo API supplies various functions that can roughly be classified by "reference type" and "contribution type." Two types exactly correspond to Photo API scopes. Correspondence between scopes and capabilities is shown below:

Scope Function
r_photo Acquisition of album list
Acquisition of photo list
Acquisition of comment list for album
Acquisition of comment list for photo
Acquisition of "like" list for photo
w_photo Creation of album
Deletion of album
Addition of photo
Deletion of photo
Comment post/deletion on/from album
Comment post/deletion on/from photo
"Like" post/deletion on/from photo

Acquisition of album list

The following is a URL to acquire the album list:

GET https://api.mixi-platform.com/2/photo/albums/[User-ID]/@self/[Album-ID]
Parameter name Value to be specified
User-ID User ID for an approved user, ”@me” indicating an approved user or a friend's user ID
Album-ID ID for an album. If it is specified, only information on the album is returned as a result of an API call. Can be omitted.

In addition, the query parameter below is supported:

Parameter name Value to be specified
accessKey If a friend is specified for User-ID and the album whose disclosure range is ”password”(visibility=access_key) is specified for Album-ID, it is necessary to specify the password as the accessKey parameter value.

The following is the result of the acquisition of album information. The example below is in JSON format.

{
  "entry": [
    {
      "created": "2010-11-02T10:42:57+09:00",
      "description": "Description of album",
      "id": "123456",
      "mediaItemCount": "200",
      "numComments": "5",
      "ownerId": "7dshdjk3mbc3w",
      "privacy": {
        "visibility": "everyone"
      },
      "thumbnailUrl": "http://ic.photo.mixi.jp/v/fbf9659ba91f6495ee9619819954a20f2476b306cd/4cd2176e/picture/u7dshdjk3mbc4x_119876_74small.jpg",
      "title": "Title of album",
      "url": "http://ic.photo.mixi.jp/v/838166e4701d0b43874b9050d2e593e0e29d9aa87e/4cd2176e/picture/u7dshdjk3mbc4x_119876_74large.jpg",
      "viewPageUrl": "http://mixi.jp/redirect_with_owner_id.pl?b=http%3A%2F%2Fphoto.mixi.jp%3A8150%2Fview_album.pl%3Falbum_id%3D111377&k=owner_id&v=7dshdjk3mbc3w",
      "owner": {
  	"thumbnailUrl":"http://profile.img.mixi.jp/photo/user/7dshdjk3mbc3w_15647919.jpg",
  	"id":"7dshdjk3mbc3w",
  	"displayName":"jack",
  	"profileUrl":"http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
      }
    },
    ・・・
  ],
  ・・・
}

The information included in each entry is as follows:

Attribute name Description
id ID to identify album
thumbnailUrl URL of thumbnail image of album
title Title character string of album
description Description of album
ownerId User ID owning this album
created Date and time when this album is created
mediaItemCount Number of photos registered on this album
url URL of large images indicating this album
numComments Number of comments attached to this album
privacy Disclosure range of this album
viewPageUrl URL of this album (view_album.pl or view_default_album.pl for easily disclosed album @default)
owner.id Owner's ID
owner.displayName Owner's nickname
owner.thumbnailUrl URL of image which is set as a profile image by owner
owner.profileUrl URL of owner's profile page

About easily disclosed album

The easy publication album is an option that is provided by mixi photo in the beginning to allow users to publish photos easily. This album is owned by each user and cannot be deleted or renamed.

When you use the Photo API to obtain the album list information without specifying Album-ID, the results do not include the information on the easy publication album. The IDs of the easy publication albums will be ”@default“. A client program must use ”@default“ for the easy publication album for each function.

Format of the privacy parameter

そThe privacy parameter indicates the publication range of the album. This privacy parameter also has a visibility parameter which indicates the disclosure range.

The following shows a list of the visibility parameter values.

Specified value Meaning
everyone Disclosure to everyone
friends Disclosure to friends
friends_of_friends Disclosure to friend's friends
top_friends Disclosure to top friends
group Disclosure to a specific group
user Disclose to specific users
access_key Disclosure using a password
self Not disclosed

Acquisition of album list created by your friend recently

The following is URL to acquire the album list recently created by friends:

GET https://api.mixi-platform.com/2/photo/albums/[User-ID]/[Group-ID]
Parameter name Value to be specified
User-ID User ID for an approved user or ”@me” indicating an approved user
Group-ID “@friends” or group ID to be acquired by Groups API

The acquisition results are in the same format as the acquisition list for normal albums.

If ”@friends” is specified as Group-ID, the list of albums recently created by your friends can be acquired.
Limited access can be granted to a group of friends by setting an ID which can be acquired through Groups API.

Acquisition of photo list

The following is a URL to acquire a list of photos registered in an album.

GET https://api.mixi-platform.com/2/photo/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]
Parameter name Value to be specified
User-ID User ID for an approved user, ”@me” indicating an approved user, or a friend's user ID.
Album-ID ID for an album from which a photo list is acquired. If your friend's "Easily disclosed" album is to be specified, ”@default” is used as the parameter value.
MediaItem-ID ID for photo. If it is specified, only information on the photo is returned as a result of the API call. Can be omitted.

In addition, the query parameter below is supported:

Parameter name Value to be specified
accessKey If a friend is specified for User-ID and the album whose disclosure range is ”password”(visibility=access_key) is specified for Album-ID, it is necessary to specify the password as the accessKey parameter value.

The following is the result of the acquisition of photo information. The example below is in JSON format.

{
  "entry": [
    {
      "albumId": "99465",
      "created": "2010-11-01T12:04:49+09:00",
      "id": "117676",
      "largeImageUrl": "http://ic.photo.mixi.jp/v/fffd76a06cf4275c267257b96eb1c2c3c06bf8e25b/4cd21765/picture/u7dshdjk3mbc4x_117676_65xga.jpg",
      "mimeType": "image/jpeg",
      "numComments": "0",
      "numFavorites": "0",
      "thumbnailUrl": "http://ic.photo.mixi.jp/v/8684fa2911a044f9de932f6ee7f00f5d46ade867c8/4cd21765/picture/u7dshdjk3mbc4x_117676_65small.jpg",
      "title": "Foo",
      "type": "IMAGE",
      "url": "http://ic.photo.mixi.jp/v/8e0e2ab248dc82fe8bf016d7bb361f6117ab0cec5f/4cd21765/picture/u7dshdjk3mbc4x_117676_65large.jpg",
      "viewPageUrl": "http://mixi.jp/redirect_with_owner_id.pl?b=http%3A%2F%2Fphoto.mixi.jp%3A8150%2Fview_photo.pl%3Fphoto_id%3D117676&k=owner_id&v=7dshdjk3mbc4x",
      "owner": {
  	"thumbnailUrl":"http://profile.img.mixi.jp/photo/user/7dshdjk3mbc3w_15647919.jpg",
  	"id":"7dshdjk3mbc3w",
  	"displayName":"jack",
  	"profileUrl":"http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
      }
    },
    ・・・
  ],
  ・・・
}

The information included in each entry is as follows:

Attribute name Description
albumId Album ID
created Data and time when this photo is uploaded
id ID to identify this photo
mimeType MIME type of this photo
numComments Number of comments added to this photo
title Title character string of this photo
type “IMAGE”fixed
thumbnailUrl URL of thumbnail image of this photo
numFavorites Number of Goods attached to this photo
url URL of large image of this photo
largeImageUrl URL of XGA size image of this photo
exifCreated Date when this photo is taken
viewPageUrl URL (view_photo.pl) of page of this photo
owner.id Owner's ID
owner.displayName Owner's nickname
owner.thumbnailUrl URL of image which is set as a profile image by owner
owner.profileUrl URL of owner's profile page

Acquisition of a photo list recently uploaded by friends

The following is a URL to acquire a list of photos recently uploaded by friends:

GET https://api.mixi-platform.com/2/photo/mediaItems/[User-ID]/[Group-ID]
Parameter name Value to be specified
User-ID User ID for an approved user or ”@me” indicating an approved user.
Group-ID “@friends” or group ID to be acquired by Groups API

The acquisition results are in the same format as the acquisition list for normal albums.

If ”@friends” is specified as Group-ID, the list of albums recently created by your friends can be acquired.
Limited access can be granted to a group of friends by setting an ID which can be acquired through Groups API.

Even if a friend uploads multiple photos simultaneously,
this API can only acquire information on a single photo.

Acquisition of comment list from album

The following is a URL to acquire the list of comments added to an album:

GET https://api.mixi-platform.com/2/photo/comments/albums/[User-ID]/@self/[Album-ID]
Parameter name Value to be specified
User-ID User ID for an approved user, ”@me” indicating an approved user, or a friend's user ID
Album-ID ID of an album from which the comment list is acquired.

In addition, the query parameter below is supported:

Parameter name Value to be specified
accessKey If a friend is specified for User-ID and the album whose disclosure range is ”password” (visibility=access_key) is specified for Album-ID, it is necessary to specify the password as the accessKey parameter value.

The acquisition result is in JSON format as shown below:

{
    "entry" : [
        "id" : "sa1pzkdg9emdd-500000004743798-sa1pzkdg9emdd-20101208110507",
        "created" : "2010-12-08T11:07:38+09:00",
        "text" : "Comment body",
        "user" : [
            "id" : "sa1pzkdg9emdd",
            "displayName" : "Nickname",
            "thumbnailUrl" : "http://profile.img.mixi.jp/photo/user/sa1pzkdg9emde_156479.jpg",
            "profileUrl" : "http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
        ]
    ],
    ・・・
}

The information included in each entry is as follows:

Attribute name Description
id ID (Comment-ID) to identify a comment
created Date and time when the comment is made. Its format is "yyyy-mm-ddThh:mm:ss+09:00". (For details, see [XSdateTime].)
text Comment body
user.id User ID of comment contributor
user.displayName Nickname of comment contributor
user.thumbnailUrl URL of a profile image of comment contributor
user.profileUrl URL of profile page of comment contributor

If the comment poster expressed in the user property is not a friend of an approved user, only id, displayName, and thumbnailUrl properties are included in the result.

Acquisition of comment list from photo

The following is a URL to acquire the list of comments added to a photo:

GET https://api.mixi-platform.com/2/photo/comments/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]
Parameter name Value to be specified
User-ID User ID for an approved user, ”@me” indicating an approved user, or a friend's user ID
Album-ID ID for an album from which a comment list is acquired. If a friend's "Easily disclosed" album is to be specified, ”@default” is used as a parameter value.
MediaItem-ID ID of photo for which comment list is to be acquired

In addition, the query parameter below is supported:

Parameter name Value to be specified
accessKey If a friend is specified for User-ID and the album whose disclosure range is ”password” (visibility=access_key) is specified for Album-ID, it is necessary to specify the password as the accessKey parameter value.

The acquisition result is in JSON format as shown below:

{
    "entry" : [
        "id" : "sa1pzkdg9emdd-500000004743798-sa1pzkdg9emdd-20101208110507",
        "created" : "2010-12-08T11:07:38+09:00",
        "text" : "Comment body",
        "user" : [
            "id" : "sa1pzkdg9emdd",
            "displayName" : "Nickname",
            "thumbnailUrl" : "http://profile.img.mixi.jp/photo/user/sa1pzkdg9emde_156479.jpg",
            "profileUrl" : "http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx"
        ]
    ],
    ・・・
}

The information included in each entry is as follows:

Attribute name Description
id ID (Comment-ID) to identify a comment
created Date and time when the comment is made. Its format is "yyyy-mm-ddThh:mm:ss+09:00". (For details, see [XSdateTime].)
text Comment body
user.id User ID of comment contributor
user.displayName Nickname of comment contributor
user.thumbnailUrl URL of a profile image of comment contributor
user.profileUrl URL of profile page of comment contributor

If the comment poster expressed in the user property is not a friend of an approved user, only id, displayName, and thumbnailUrl properties are included in the result.

Acquisition of "like" list from photo

The following is a URL to acquire the list of "likes" added to a photo.

GET https://api.mixi-platform.com/2/photo/favorites/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]
Parameter name Value to be specified
User-ID User ID for an approved user, ”@me” indicating an approved user, or a friend's user ID
Album-ID ID for an album from which the "like" list is acquired. If your friend's "Easily disclosed" album is to be specified, ”@default” is used as the parameter value.
MediaItem-ID ID of photo for which the "like" list is to be acquired

In addition, the query parameter below is supported:

Parameter name Value to be specified
accessKey If a friend is specified for User-ID and the album whose disclosure range is ”password” (visibility=access_key) is specified for Album-ID, it is necessary to specify the password as the accessKey parameter value.

The acquisition result is in JSON format as shown below:

{
    "entry" : [
        {
            "id" : "sa1pzkdg9emdd",
            "displayName" : "Nickname",
            "thumbnailUrl" : "http://profile.img.mixi.jp/photo/user/sa1pzkdg9emde_156479.jpg",
            "profileUrl" : "http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx",
            "created" : "2010-11-02T10:42:57+09:00"
        },
        ・・・
    ],
    ・・・
}

The information included in each entry is as follows:

Attribute name Description
id User ID of "like" poster
displayName Nickname of "like" poster
thumbnailUrl URL of a profile image of "like" poster
profileUrl URL of profile page of "like" poster
created Date and time when the "like" was posted. The format is "yyyy-mm-ddThh:mm:ss+09:00". (For details, see [XSdateTime].)

If the "like" poster is not a friend of an approved user, only id, displayName, and thumbnailUrl properties are included in the result.

Creation of album

The following is a URL to create a new album:

POST https://api.mixi-platform.com/2/photo/albums/[User-ID]/@self
Parameter name Value to be specified
User-ID User ID for an approved user or ”@me” indicating an approved user

The ID to be specified as a User-ID parameter is only ”@me”, which indicates the user who approves the access token. Any other user ID or ”@friends” cannot be specified.

The information on an album to be created may be included in the request body using either the x-www-form-urlencoded or the application/json formats. At that time, it is necessary for the Content-Type request header to clearly indicate which is used. UTF-8 should be used as the character code. The information to be specified is as follows:

Parameter name Description Mandatory
title Title character string of album
description Description of album
visibility Disclosure range specification of album
accessKey Password to limit album disclosure Mandatory only if ”access_key” is specified in the visibility parametervisibility

The disclosure range to be specified by the visibility parameter is as follows:

Specified value Meaning
everyone Disclose to everyone
friends Disclose to friends
friends_of_friends Disclose to friend's friends
top_friends Disclose to good friends
access_key Disclose using a password
self Not disclosed

Specification in the x-www-form-urlencoded format is as follows:

title= Title &description= Description &visibility=everyone

Specification in the application/json format is as follows:

{
  "title" : "Title",
  "description" : "Desctiption",
  "privacy" : {
      "visibility" : "access_key",
      "accessKey" : "secret"
  }
}

If a new album is created successfully, HTTP status code; 201 and the content below are returned in the body of the response.

{
  "id" : [Album-ID]
}

The created album can be accessed using the Album-ID returned.

Deletion of album

URL below is used to delete an album:

DELETE https://api.mixi-platform.com/2/photo/albums/[User-ID]/@self/[Album-ID]
Parameter name Value to be specified
User-ID User ID for an approved user or ”@me”indicating an approved user
Album-ID ID of an album to be deleted

The ID to be specified as a User-ID parameter is only ID of a user who approves the access token or ”@me” which indicates the approving user itself. Any other user ID or ”@friends” cannot be specified.

If deletion is successful, HTTP status code: 200 is returned. Photos registered in the album are deleted simultaneously.

Comment contribution to album

URI below is used to contribute a comment to an album:

POST https://api.mixi-platform.com/2/photo/comments/albums/[User-ID]/@self/[Album-ID]
Parameter name Value to be specified
User-ID User ID for an approved user, ”@me” indicating an approved user, or a friend's user ID
Album-ID ID for an album to which a comment is contributed. ”@default”, which indicates "Easily disclosed" album cannot be specified.

In addition, the query parameter below is supported:

Parameter name Value to be specified
accessKey If a friend is specified for User-ID and the album whose disclosure range is ”password” (visibility=access_key) is specified for Album-ID, it is necessary to specify the password as the accessKey parameter value.

The comment body may be specified in the request body using either the application/json or the application/x-www-form-urlencoded format. At that time, Content-Type request header should be used to indicate which is used.

The following is in the application/json format:

{
    "text" : "Comment Body"
}

The following is for the application/x-www-form-urlencoded format:

text=%E3%82%B3%E3%83%A1%E3%83%B3%E3%83%88%E6%9C%AC%E6%96%87

If comment is posted successfully, HTTP status code: 201 is returned.

Comment deletion from album

The following is a URL to delete a comment which has been posted to an album:

DELETE https://api.mixi-platform.com/2/photo/comments/albums/[User-ID]/@self/[Album-ID]/[Comment-ID]
Parameter name Value to be specified
User-ID User ID for an approved user, ”@me” indicating an approved user, or a friend's user ID
Album-ID ID for an album from which a comment is deleted. ”@default”, which indicates "Easily disclosed" album cannot be specified.
Comment-ID ID for a comment to be deleted

In addition, the query parameter below is supported:

Parameter name Value to be specified
accessKey If a friend is specified for User-ID and the album whose disclosure range is ”password” (visibility=access_key) is specified for Album-ID, it is necessary to specify the password as the accessKey parameter value.

If the comment is deleted successfully, HTTP status code: 200 is returned.

Addition of photo

The URL below is used to add a photo to an album:

POST https://api.mixi-platform.com/2/photo/mediaItems/[User-ID]/@self/[Album-ID]
Parameter name Value to be specified
User-ID User ID for an approved user or ”@me” indicating an approved user
Album-ID ID for an album to which the photo is added
title Title of photo to be registered. Can be omitted.

The ID to be specified as a User-ID parameter only includes the ID of a user who approves the access token or ”@me” which corresponds to an authorized user. Any other user ID or ”@friends” cannot be used.

The title parameter value should be specified as the query parameter for the title of the photo to be added. The binary data of the image file to be registered is specified in the request body. The request will appear similar to the following:

POST /2/photo/mediaItems/@me/@self/12345?title=Hello HTTP/1.1
Host: api.mixi-platform.com
Content-Type: image/jpeg
Content-Length: 123456

d84ba376eaaa786249...

If a photo is added successfully, HTTP status code: 201 and the content below are returned similar to the following:

{
  "id" : [MediaItem-ID]
}

The added photo can be accessed using the MediaItem-ID returned.

Deletion of photo

The URL below is used to delete a photo:

DELETE https://api.mixi-platform.com/2/photo/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]
Parameter name Value to be specified
User-ID User ID for an approved user or ”@me” indicating an approved user
Album-ID ID of an album registering photo to be deleted
MediaItem-ID ID of photo to be deleted

The ID to be specified as a User-ID parameter only includes the ID of a user who approves the access token or ”@me” which corresponds to an authorized user. Any other user ID or ”@friends” cannot be used.

If successfully deleted, the HTTP status code: 200 is returned.

Comment contribution to photo

The URL below is used to post a comment for a photo:

POST https://api.mixi-platform.com/2/photo/comments/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]
Parameter name Value to be specified
User-ID User ID for an approved user, ”@me” indicating an approved user or a friend's user ID
Album-ID ID of an album including a photo to which a comment is to be posted
MediaItem-ID ID of photo to which a comment is posted

In addition, the query parameter below is supported:

Parameter name Value to be specified
accessKey If a friend is specified for User-ID and the album whose disclosure range is ”password” (visibility=access_key) is specified for Album-ID, it is necessary to specify the password as the accessKey parameter value.

The comment body may be specified in the request body using either the application/json or the application/x-www-form-urlencoded format. At that time, Content-Type request header should be used to indicate which is used.

The following is in the application/json format:

{
    "text" : "Comment Body"
}

The following is for the application/x-www-form-urlencoded format:

text=%E3%82%B3%E3%83%A1%E3%83%B3%E3%83%88%E6%9C%AC%E6%96%87

If comment is posted sucessfully, the HTTP status code: 201 is returned.

Deletion of a photo comment

The URL below is used to delete a comment posted for a photo:

DELETE https://api.mixi-platform.com/2/photo/comments/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]/[Comment-ID]
Parameter name Value to be specified
User-ID User ID for an approved user, ”@me” indicating an approved user, or a friend's user ID
Album-ID ID of an album of photos which includes a comment to be deleted
MediaItem-ID ID of a photo which includes a comment to be deleted
Comment-ID ID of a comment to be deleted

In addition, the query parameter below is supported:

Parameter name Value to be specified
accessKey If a friend is specified for User-ID and the album whose disclosure range is ”password” (visibility=access_key) is specified for Album-ID, it is necessary to specify the password as the accessKey parameter value.

If a comment is successfully deleted, the HTTP status code: 200 is returned.

Adding a "like" to a photo

The URL below is used to "like" a photo:

POST https://api.mixi-platform.com/2/photo/favorites/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]
Parameter name Value to be specified
User-ID User ID of friend
Album-ID ID of an album of photos which includes a "like"
MediaItem-ID ID of photo which includes "like"

In addition, the query parameter below is supported:

Parameter name Value to be specified
accessKey If a friend is specified for User-ID and the album whose disclosure range is ”password” (visibility=access_key) is specified for Album-ID, it is necessary to specify the password as the accessKey parameter value.

If a "like" is successfully added, HTTP status code: 201 is returned.

Deleting a "like" from a photo

The URL below is used to delete a "like" from a photo:

DELETE https://api.mixi-platform.com/2/photo/favorites/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]/[Favorite-User-ID]
Parameter name Value to be specified
User-ID User ID for an approved user, ”@me” indicating an approved user, or a friend's user ID
Album-ID ID of an album of photos including a "like" to be deleted. ”@default” which represents "Easily disclosed" albums cannot be specified.
MediaItem-ID ID of photo including a "like" to be deleted
Favorite-User-ID User ID of the poster of the "like" to be deleted. If the poster to the target photo is an approved user, "likes" posted by other users can be deleted as well.

In addition, the query parameter below is supported:

Parameter name Value to be specified
accessKey If a friend is specified for User-ID and the album whose disclosure range is ”password” (visibility=access_key) is specified for Album-ID, it is necessary to specify the password as the accessKey parameter value.

If a "like" is deleted successfully, the HTTP status code: 200 is returned.

Paging and expression formats

The Photo API supports paging. Supported expression format include the JSON format or the x-www-form-urlencoded format.

Paging typically uses startIndex, the count parameter specification, but can occasionally use the next, prev parameter method.

UTF-8 is used as the character code for request and response.

TOP OF THIS PAGE