NAV
shell

はじめに

API Endpoint

https://api.clip.cc

Clip APIへようこそ! 私たちのAPIのエンドポイントにアクセスするだけで Clip Appでスキャン可能なQRコードを作成、購入、ダウンロードすることができます。
そして、このQRコードをあなたのプロダクトに組み込んで自由に再販することができます。

Clip APIはRESTを基本に構成しています。
全てのAPIによるレスポンスはエラーも含めて、JSON形式で返します。

費用について

QRコードごとの費用

  1. Single Content (1 video): $1/QR code
  2. Multiple Contents (2 - 20 videos): $5/QR code

セットする動画の数と、発行するQRコードの数によって商品単価が異なります。 QRコードを複数枚発行する理由については次のセクションで後述します。

QRコードのアクセス制限について

  • 動画付きのポスターを100枚作成してプロモーションに利用する。
    • QRコードを100個購入してください。
  • 動画付きの結婚式のフォトアルバムを新郎新婦や親族のために10冊作成して販売する。
    • QRコードを10個購入してください。

ClipのQRコードには、スキャン可能な端末の数に制限があります(同じ端末であれば無制限です)。なので、あなたが販売するプロダクトの印刷枚数にあわせてQRコードを同じ数だけ購入してください。 APIはQRコードの画像を購入した数量だけ生成します。

API利用フロー

  1. QR Codeを作る
  2. QR Codeを取得
    1. status = completedになるまでポーリングする。
    2. status = failedの場合はパラメータを見なおしてStep 1へ。
  3. テスト用QRコードでARの動作確認 Optional
    • 例: PC向けにClip APIを提供する場合はディスプレイに表示してテストをする。
  4. 印刷枚数を指定して購入前に料金を確認 Optional
  5. 1週間以内にQR Codeを購入する

認証

# With shell, you can just pass the correct header with each request
curl -u "test-clip-api-key:" "api_endpoint_here"

Make sure to replace test-clip-api-key with your API key.

リクエストにAPIキーを含めることでAPIの認証を行うことができます。 APIへの認証はBASIC認証を用いて行います。APIキーをBASIC認証のユーザー名として入力してください。パスワードは必要ありません。

すべてのAPIリクエストはHTTPS上でアクセスして下さい。HTTPでアクセスした場合は失敗します。 ClipはすべてのAPIリクエストがこの方式で認証されていることを期待しています。

APIキーの種類

APIキーにはサンドボックス用と本番環境用があります。 サンドボックス用のAPIキーを利用することで、QRコードの購入処理を実際の請求を発生させずに行うことができます。サンドボックス用のAPIキーで作成されたQRコードは1週間で無効となりスキャンしてもコンテンツが見られなくなりますので予めご注意ください。

エラー

# 認証情報なしでAPIにリクエストする
curl -v https://api.clip.cc/v1/qrcodes

The above command returns JSON structured like this:

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
{"type":"invalid_request_error","message":"Oops! unauthorized"}

ClipはHTTPレスポンスコードを使いAPIリクエストの成功もしくは失敗を示します。コードが2xxの範囲であれば成功を意味し、4xxの範囲であればリクエストされた情報に起因するエラーであることを示します(例えば、パラメータが不足している、リクエストしたリソースが存在しない。等)、そして5xxの範囲であればClipのサーバ側でのエラーであることを示します。

また、エラーが起こっている場合、レスポンスのオブジェクトは下記の属性を含みます。

属性
type エラーの種類。 invalid_request_error, api_error が入ります。
message optional 人間が読みやすいエラー内容。現在は開発用メッセージが入ります。

マーカーの準備

マーカーとは

マーカーは以下の仕様を満たしている必要があります。

  • JPEG
    • Baseline(Non Progressive)
    • sRGB colorspace
  • 250px x 250px

マーカーとは、動画を表示する位置を指定するため標識となる画像のことです。 APIはリクエストされたマーカーが仕様を満たしているかを確認します。 この他にマーカーテストが実施されます。

コンテンツの準備

コンテンツは以下の仕様を満たしている必要があります。

  • Container: .mp4
  • Audio
    • Codec: AAC-LC
    • Sample rate: 48khz 以下
    • Bitrate: 128 kpbs 以下
  • Video
    • Codec: H.264
    • Bitrate: 2000 kbps 以下
    • Resolution: 360p
    • e.g. 360px x 360px, 640px x 360px, 480px x 360px
    • Supported landscape and portrait
  • File size: 10MB 以下

コンテンツとは、マーカーをClip appでスキャンした時に再生される動画のことです。

QR Code

QR Code Object

{
  "id": 8,
  "status": "purchased",
  "test_image_url": "https://api.clip.cc/developer/qrcode?slug=test_9bqhoy",
  "production_image_list": [
    { "image_url": "https://api.clip.cc/developer/qrcode?link_id=11" },
    { "image_url": "https://api.clip.cc/developer/qrcode?link_id=12" }
  ],
  "video_errors": [
    ["fetch failed"], []
  ],
  "image_errors": [
    [], []
  ]
}

実際にはstatusがfailedの場合のみvideo_errors, image_errorsに値が入ります。

Attributes
id integer
status string processing, completed, failed, expired, purchased が入ります。
test_image_url string statusがcompletedの場合、テスト用のQRコード画像をダウンロードするためのURLが入ります。それ以外の場合は空文字列。
production_image_list list 購入したQRコードのリスト。中身はHashで、image_url attributeにQRコード画像のURLが入ります。
video_errors list 動画をバリデーションした結果のエラーリスト。リストの長さは動画のファイル数と同じだけ存在します。エラーがない場合は空配列になります。
image_errors list 画像をバリデーションした結果のエラーリスト。形式はvideo_errorsと同様です。

status

  • processing: 処理中。
  • completed: 処理完了。購入ができます。
  • failed: 処理失敗。
  • expired: 作成から1週間経過しても購入されなかったため有効期限切れ。
  • purchased: 購入済み。

QR Codeを作る

# Example request
curl -u test-clip-api-key: https://api.clip.cc/v1/qrcodes \
-X POST \
--data-urlencode "video_url=http://clip-dev.s3.amazonaws.com/test_resources/public_api/valid.mp4,http://clip-dev.s3.amazonaws.com/test_resources/public_api/valid2.mp4" \
--data-urlencode "image_url=http://clip-dev.s3.amazonaws.com/test_resources/public_api/valid.jpg,http://clip-dev.s3.amazonaws.com/test_resources/public_api/valid2.jpg"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Status: 200 OK
X-App-Sandbox: 1
{
  "id": 1,
  "status": "processing",
  "test_image_url": "",
  "production_image_list": [
  ],
  "video_errors": [
  ],
  "image_errors": [
  ]
}

HTTP Request

POST https://api.clip.cc/v1/qrcodes

Parameters
image_url required マーカー画像のURL。ClipはこのURLをfetchしてClipサーバ内に保存し、マーカーとして利用します。
video_url required 動画のURL。ClipはこのURLをfetchしてClipサーバ内に保存し、コンテンツとして利用します。

Multiple content

QR Codeに複数コンテンツを付与する場合は,区切りでURLを複数指定してください。image_urlvideo_urlの要素数が同じである必要があります。

Response

QR Code object

QR Codeを取得する

# Example request
curl -u test-clip-api-key: https://api.clip.cc/v1/qrcodes/1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-App-Sandbox: 1
{
  "id": 3,
  "status": "completed",
  "test_image_url": "https://api.clip.cc/developer/qrcode?slug=test_CjuoUw",
  "production_image_list": [],
  "image_errors": [
    [], []
  ],
  "video_errors": [
    [], []
  ]
}

HTTP Request

GET https://api.clip.cc/v1/qrcodes/:qrcode_id

Parameters
qrcode_id required QR Code Objectid

Response

QR Code object

QR Codeをすべて取得する

# Example request
curl -u test-clip-api-key: https://api.clip.cc/v1/qrcodes
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-App-Sandbox: 1
{
  "all": 2,
  "count": 2,
  "offset": 0,
  "qrcodes": [
    {
      "id": 3,
      "status": "completed",
      "image_errors": [[],[]],
      "video_errors": [[],[]],
      "test_image_url": "https://api.clip.cc/developer/qrcode?slug=test_CjuoUw",
      "production_image_list": []
    },
    {
      "id": 1,
      "status": "purchased",
      "image_errors": [[]],
      "video_errors": [[]],
      "test_image_url": "https://api.clip.cc/developer/qrcode?slug=test_cGP1b6",
      "production_image_list": [
        {"image_url": "https://api.clip.cc/developer/qrcode?link_id=1"}, ...
      ]
    }, ...
  ]
}

HTTP Request

GET https://api.clip.cc/v1/qrcodes

Parameters
count optional デフォルトは10
offset optional デフォルトは0

Response

Attributes
all integer 全体の件数
count integer 実際に取得した件数
offset integer
qrcodes list QR Code Object のリスト

QR Codeの価格を取得する

curl -u test-clip-api-key: https://api.clip.cc/v1/qrcodes/3/price?quantity=10
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-App-Sandbox: 1
{"price":1000}

HTTP Request

GET https://api.clip.cc/v1/qrcodes/:qrcode_id/price

Parameters
qrcode_id required QR Code Objectid
quantity required 購入するQRコードの数

Response

Attributes
price integer 合計金額。単位はUSDに100を掛けたもの(例: 1USD = 100)。費用について

QR Codeを購入する

curl -u test-clip-api-key: https://api.clip.cc/v1/qrcodes/3/purchase -X POST -d "quantity=2"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-App-Sandbox: 1
{
  "id": 3,
  "status": "purchased",
  "image_errors": [[]],
  "video_errors": [[]],
  "test_image_url": "https://api.clip.cc/developer/qrcode?slug=test_cGP1b6",
  "production_image_list": [
    {"image_url": "https://api.clip.cc/developer/qrcode?link_id=1"},
    {"image_url": "https://api.clip.cc/developer/qrcode?link_id=2"}
  ]
}

HTTP Request

POST https://api.clip.cc/v1/qrcodes/:qrcode_id/purchase

Parameters
qrcode_id required QR Code Objectid
quantity required 購入するQRコードの数

Response

QR Code object