NAV
shell

Introduction

API Endpoint

https://api.clip.cc

Welcome to the Clip API! You can use our API to access the Clip API endpoints, which can create, purchase, and download a QR Code that can be read by the Clip app. Our API is organized around REST. All responses including errors are formatted in JSON.

Cost

QR Code Costs

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

The product cost is different depending on the amount of videos you would like to set, and QR codes you would like to produce. Reasons regarding producing multiple QR codes are written below.

QR Code Limitation

Example

  • Printing 100 posters with a video for promotion.
    • You must purchase 100 QR codes.
  • Producing 10 wedding photo albums that includes video, and sell them to the newly weds, and family.
    • You must pruchase 10 QR codes.

There is a limit in the amount of devices that can read a QR code (you can read the QR code as many times as you want using the same device) therefore you must purchase the same number of QR codes as many as the products you want to sell. The API will only play back the amount of Clips purchased.

API Usage Flow

  1. Create QR Code
  2. Acquire QR Code
    1. status = completedkeep polling until completed.
    2. status = failed check parameter if this happens. To Step 1.
  3. Check the AR video with the test QR Code. Optional
    • example: When providing Clip API for PC, display on a monitor and test.
  4. Specify the number of prints, before purchasing Confirm cost Optional
  5. Within 1 week Purchase QR Code

Authentication

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

In order to use the API you must send your API key as basic auth credentials in the request. No password is required.

Please access all the API requests through HTTPS. Your request will fail if you try to access through HTTP. We anticipate that all the Clip API requests are authenticated through this method.

Types of API Key

You can test freely the purchase process for QR codes if you use the API key for sandbox. Keep in mind that the QR code will become invalid after 1 week and you will not able to see the contents.

Error

# Making a request to the API without auth information
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 will indicate both successful and unsuccessful API requests using HTTP response code. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a requested resource does not exist, etc.), and codes in the 5xx range indicate an error with Clip’s servers. Also, if there are errors occuring, the object response will include the attributes below.

Attributes
type Error type. Can be invalid_request_error, api_error.
message optional A human-readable message giving more details about the error. Currently, a message to assist development.

Preparing the Marker

Marker

You are required to fulfill the specifications below regarding the Marker.

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

The ‘marker’ is an image that locates the video display position. The API makes a request to check if the marker fulfills the specification requirements. Besides this, other marker tests will be operated.

Preparing the Content

You are required to fulfill the specifications below regarding the preparation of the contents.

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

The content is what is played when the marker is scanned with the 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": [
    [], []
  ]
}

the value will be in video_errors,image_errors, only if there is a failed status.

Attributes
id integer
status string can be processing, completed, failed, expired, purchased.
test_image_url string if the status is completed, the value will be the download URL for the test QR code. Anything else is an empty string "".
production_image_list list Purchased QR code list. Can be the image_url attribute for the QR code image within Hash.
video_errors list Video will be validated. If there are any errors, a message will be put into an array.
image_errors list Image will be validated. If there are any errors, a message will be put into an array.

status

  • processing: Validating the movie and image, the QR code is being processed.
  • completed: The QR code processing has completed. You can purchase the QR code.
  • failed: QR code failed to process.
  • expired: 1 week has expired so the processed QR code has become invalid.
  • purchased: The QR code has been purchased.

Create 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 Marker Clip will fetch this URL, store on the server and use as the video marker.
video_url required Video Clip will fetch this URL, store on the server and use as the content.

Multiple content

If you are assigning multiple contents for one QR code, use , as a break, and set multiple URL. You are required to have the same number of image_urland video_url.

Response

QR Code object

Acquire 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 The id for QR Code Object.

Response

QR Code object

Acquire All The QR Codes

# 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 Default is 10
offset optional Default is 0

Response

Attributes
all integer Total number of data.
count integer Actual acquired number of data.
offset integer
qrcodes list QR Code Object list

Acquire QR Code price

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 The id for QR Code Object.
quantity required The quantity of QR codes you will purchase

Response

Attributes
price integer Total Price。The unit price is USD multiplied by 100 (example: 1USD = 100).Regarding Cost

Purchase 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 The id for QR Code Object.
quantity required The quantity of QR codes you will purchase

Response

QR Code object