mixi Developer Center (ミクシィ デベロッパーセンター)

ユーザがmixi上でコミュニケーションを楽しむためのコンテンツとして、フォトは非常に重要です。フォトには、そのユーザの想い出や感情が詰まっています。多くのユーザが、手軽にフォトをmixiに登録し、友人とシェアをしたいと考えています。写真を撮影してすぐにmixiに登録したい、この願いをPhoto APIは叶えてくれます。

ここでは、Photo APIの使用方法について説明します。

事前に必要なもの

Photo APIを利用するためには、以下の情報をすでに入手している必要があります。

• “r_photo”または”w_photo”スコープおよびその両方について認可されたアクセストークン

上記以外のスコープで認可されたアクセストークンを使用して、Photo APIにアクセスすることはできません。アクセストークンの入手方法については、認証認可手順のページをご覧ください。

Photo APIで提供される機能とスコープ

Photo APIでは様々な機能が提供されますが、それらは大きく「参照系」「投稿系」の2つに分類されます。この分類は、そのままPhoto APIを利用するためのスコープに対応します。以下に、スコープと各機能の対応を示します。

アルバム一覧の取得

アルバム一覧を取得するためのURIは以下となります。

GET https://api.mixi-platform.com/2/photo/albums/[User-ID]/@self/[Album-ID]

更に、以下のクエリパラメータをサポートします。

アルバム情報の取得結果は、以下のようになります。下記の例は、JSON形式です。

{
  "entry": [
    {
      "created": "2010-11-02T10:42:57+09:00",
      "description": "アルバムの説明",
      "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": "アルバムのタイトル",
      "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;
      }
    },
    ・・・
  ],
  ・・・
}

個々のエントリに含まれる情報は、以下となります。

かんたん公開アルバムについて

mixiフォトでは、写真を簡単に公開するために最初から各ユーザ向けに「かんたん公開」アルバムが提供されています。これは全ユーザが所有しているアルバムであり、削除や名称変更などはできません。

Photo APIを利用して、Album-IDの指定なしにアルバム一覧情報を取得した際には、その取得結果の中に「かんたん公開」アルバムの情報は含まれません。「かんたん公開」アルバムのIDは”@default“となりますので、各機能の中でクライアントプログラム側が「かんたん公開」アルバムに”@default”を使用して対応してください。

“privacy” パラメーターの形式

そのアルバムの公開範囲は、privacyパラメータ値で得られます。このprivacyパラメータは、更にvisibilityパラメータを持ちます。公開範囲の種別は、visibilityパラメータ値により表現されます。

visibilityパラメータ値の一覧は以下となります。

最近友人が作成したアルバム一覧の取得

友人が最近作成したアルバムの一覧を取得するためのURIは以下となります。

GET https://api.mixi-platform.com/2/photo/albums/[User-ID]/[Group-ID]

取得結果は通常のアルバム一覧取得時と同様の形式です。

Group-IDとして”@friends”を指定した場合は、友人が最近作成したアルバムの一覧が取得できます。
Groups APIで取得できるidを指定することで、そのグループに所属している友人のみに限定することが可能です。

フォト一覧の取得

あるアルバムに登録されているフォトの一覧を取得するためのURIは以下となります。

GET https://api.mixi-platform.com/2/photo/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]

更に、以下のクエリパラメータをサポートします。

フォト情報の取得結果は、以下のようになります。下記の例は、JSON形式です。

{
  "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": "ふぁー",
      "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;
      }
    },
    ・・・
  ],
  ・・・
}

個々のエントリに含まれる情報は、以下となります。

最近友人がアップロードしたフォト一覧の取得

友人が最近アップロードしたフォトの一覧を取得するためのURIは以下となります。

GET https://api.mixi-platform.com/2/photo/mediaItems/[User-ID]/[Group-ID]

取得結果は通常のフォト一覧取得時と同様の形式です。

Group-IDとして”@friends”を指定した場合は、友人が最近投稿したフォトの一覧が取得できます。
Groups APIで取得できるidを指定することで、そのグループに所属している友人のみに限定することが可能です。

友人が複数枚のフォトをまとめてアップロードしていた場合、このAPIで取得できるフォトはそのうちの
1枚の情報のみとなります。

アルバムへのコメント一覧の取得

アルバムに対して付けられたコメントの一覧を取得するためのURIは以下となります。

GET https://api.mixi-platform.com/2/photo/comments/albums/[User-ID]/@self/[Album-ID]

更に、以下のクエリパラメータをサポートします。

取得結果は、以下のようなJSON形式となります。

{
    "entry" : [
        "id" : "sa1pzkdg9emdd-500000004743798-sa1pzkdg9emdd-20101208110507",
        "created" : "2010-12-08T11:07:38+09:00",
        "text" : "コメント本文",
        "user" : [
            "id" : "sa1pzkdg9emdd",
            "displayName" : "ニックネーム",
            "thumbnailUrl" : "http://profile.img.mixi.jp/photo/user/sa1pzkdg9emde_156479.jpg",
            "profileUrl" : "http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx;
        ]
    ],
    ・・・
}

個々のエントリに含まれる情報は、以下となります。

userプロパティにて表現されるコメント投稿者が認可ユーザと友人関係ではない場合は、id、displayNameおよびthumbnailUrlプロパティのみが結果に含まれます。

フォトへのコメント一覧の取得

フォトに対して付けられたコメントの一覧を取得するためのURIは以下となります。

GET https://api.mixi-platform.com/2/photo/comments/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]

更に、以下のクエリパラメータをサポートします。

取得結果は、以下のようなJSON形式となります。

{
    "entry" : [
        "id" : "sa1pzkdg9emdd-500000004743798-sa1pzkdg9emdd-20101208110507",
        "created" : "2010-12-08T11:07:38+09:00",
        "text" : "コメント本文",
        "user" : [
            "id" : "sa1pzkdg9emdd",
            "displayName" : "ニックネーム",
            "thumbnailUrl" : "http://profile.img.mixi.jp/photo/user/sa1pzkdg9emde_156479.jpg",
            "profileUrl" : "http://mixi.jp/redirect_friend_api.pl?puid=xxxxxxxxxxxxx&client_id=xxxxxxxx;
        ]
    ],
    ・・・
}

個々のエントリに含まれる情報は、以下となります。

userプロパティにて表現されるコメント投稿者が認可ユーザと友人関係ではない場合は、id、displayNameおよびthumbnailUrlプロパティのみが結果に含まれます。

フォトへのイイネ一覧の取得

フォトに対して付けられたイイネの一覧を取得するためのURIは以下となります。

GET https://api.mixi-platform.com/2/photo/favorites/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]

更に、以下のクエリパラメータをサポートします。

取得結果は、以下のようなJSON形式となります。

{
    "entry" : [
        {
            "id" : "sa1pzkdg9emdd",
            "displayName" : "ニックネーム",
            "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"
        },
        ・・・
    ],
    ・・・
}

個々のエントリに含まれる情報は、以下となります。

イイネ投稿者が認可ユーザと友人関係ではない場合は、id、displayNameおよびthumbnailUrlプロパティのみが結果に含まれます。

アルバムの作成

新規にアルバムを作成するためのURIは以下となります。

POST https://api.mixi-platform.com/2/photo/albums/[User-ID]/@self

User-IDパラメータとして指定可能なIDは、アクセストークンを認可したユーザ自身を示す”@me”のみとなります。他のユーザのIDあるいは”@friends”などは指定することはできません。

作成するアルバムの情報は、リクエストボディに「x-www-form-urlencoded」形式または「application/json」形式のどちらかで指定します。この際、Content-Typeリクエストヘッダにて、どちらの形式を使用したかを明示する必要があります。文字コードはUTF-8を使用してください。指定可能な情報は以下となります。

visibilityパラメータで指定可能な公開範囲は、以下となります。

「x-www-form-urlencoded」形式での指定は、以下のようになります。

title=タイトル&description=説明&visibility=everyone

「application/json」形式での指定は、以下のようになります。

{
  "title" : "タイトル",
  "description" : "説明",
  "privacy" : {
      "visibility" : "access_key",
      "accessKey" : "secret"
  }
}

新規アルバムの作成に成功した場合は、HTTPステータスコード201および以下の内容がレスポンスボディとして返却されます。

{
  "id" : [Album-ID]
}

これで返却されるAlbum-IDにより、作成されたアルバムにアクセスすることができるようになります。

アルバムの削除

あるアルバムを削除したい時には以下のURIを使用します。

DELETE https://api.mixi-platform.com/2/photo/albums/[User-ID]/@self/[Album-ID]

User-IDパラメータとして指定可能なIDは、アクセストークンを認可したユーザのID、もしくは認可ユーザ自身を示す”@me”のみとなります。他のユーザのIDあるいは”@friends”などは指定することはできません。

削除に成功した場合は、HTTPステータスコード200が返却されます。そのアルバムに登録されていたフォトも同時に削除されます。

アルバムへのコメント投稿

あるアルバムへのコメントの投稿を行うためのURIは以下となります。

POST https://api.mixi-platform.com/2/photo/comments/albums/[User-ID]/@self/[Album-ID]

更に、以下のクエリパラメータをサポートします。

コメント本文は、application/jsonもしくはapplication/x-www-form-urlencodedのどちらかの形式でリクエストボディに指定します。この際、Content-Typeリクエストヘッダにて、どちらの形式を利用したかを指定します。

application/json形式の場合は、以下のようになります。

{
    "text" : "コメント本文"
}

application/x-www-form-urlencoded形式の場合は、以下のようになります。

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

コメントの投稿に成功した場合は、HTTPステータスコードとして201が返却されます。

アルバムへのコメントの削除

あるアルバムに投稿されたコメントを削除するためのURIは以下となります。

DELETE https://api.mixi-platform.com/2/photo/comments/albums/[User-ID]/@self/[Album-ID]/[Comment-ID]

更に、以下のクエリパラメータをサポートします。

コメントの削除に成功した場合は、HTTPステータスコード200が返却されます。

フォトの追加

あるアルバムにフォトを追加したい場合は以下のURIを使用します。

POST https://api.mixi-platform.com/2/photo/mediaItems/[User-ID]/@self/[Album-ID]

User-IDパラメータとして指定可能なIDは、アクセストークンを認可したユーザのID、もしくは認可ユーザ自身を示す”@me”のみとなります。他のユーザのIDあるいは”@friends”などは指定することはできません。

追加するフォトのタイトル文字列は、クエリパラメータとしてtitleパラメータ値を指定します。登録する画像ファイルは、リクエストボディとしてそのファイルのバイナリデータを指定します。具体的には、以下のようなリクエストとなります。

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...

フォトの追加に成功した場合は、HTTPステータスコードとして201、およびレスポンスボディに以下の内容が返却されます。

{
  "id" : [MediaItem-ID]
}

これで返却されるMediaItem-IDにより、追加されたフォトにアクセスすることができるようになります。

フォトの削除

あるフォトを削除したい時には以下のURIを使用します。

DELETE https://api.mixi-platform.com/2/photo/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]

User-IDパラメータとして指定可能なIDは、アクセストークンを認可したユーザのユーザID、もしくは認可ユーザ自身を示す”@me”のみとなります。他のユーザのIDあるいは”@friends”などは指定することはできません。

削除に成功した場合は、HTTPステータスコード200が返却されます。

フォトへのコメント投稿

あるフォトへのコメントの投稿を行うためのURIは以下となります。

POST https://api.mixi-platform.com/2/photo/comments/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]

更に、以下のクエリパラメータをサポートします。

コメント本文は、application/jsonもしくはapplication/x-www-form-urlencodedのどちらかの形式でリクエストボディに指定します。この際、Content-Typeリクエストヘッダにて、どちらの形式を利用したかを指定します。

application/json形式の場合は、以下のようになります。

{
    "text" : "コメント本文"
}

application/x-www-form-urlencoded形式の場合は、以下のようになります。

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

コメントの投稿に成功した場合は、HTTPステータスコードとして201が返却されます。

フォトへのコメントの削除

あるフォトに投稿されたコメントを削除するためのURIは以下となります。

DELETE https://api.mixi-platform.com/2/photo/comments/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]/[Comment-ID]

更に、以下のクエリパラメータをサポートします。

コメントの削除に成功した場合は、HTTPステータスコード200が返却されます。

フォトへのイイネ投稿

あるフォトにイイネを投稿するためのURIは以下となります。

POST https://api.mixi-platform.com/2/photo/favorites/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]

更に、以下のクエリパラメータをサポートします。

投稿に成功した場合は、HTTPステータスコードとして201が返却されます。

フォトへのイイネの削除

あるフォトに投稿されたイイネを削除するためのURIは以下となります。

DELETE https://api.mixi-platform.com/2/photo/favorites/mediaItems/[User-ID]/@self/[Album-ID]/[MediaItem-ID]/[Favorite-User-ID]

更に、以下のクエリパラメータをサポートします。

イイネの削除に成功した場合は、HTTPステータスコード200が返却されます。

ページング、表現形式

Photo APIは、ページングをサポートします。サポートされる表現形式は、JSON形式もしくはx-www-form-urlencoded形式となります。

ページングに関しては、基本的にstartIndex, countパラメータ指定によるものとなりますが、一部next, prevパラメータによる方式が採用されている箇所があります。

文字コードについては、リクエスト時およびレスポンス時の両方において、UTF-8となります。