서버 API

모든 API 요청은 REST-스타일 URL에 표준 HTTP 요청입니다. 응답은 JSON 또는 이미지 입니다 (결과를 가져올 때)

인증

API는 표준 HTTP 기본 액세스 인증을 이용합니다. API에 대한 모든 요구들은 사용자로 API Id 비밀번호로 API 키로 API Id와 함께 귀하의 API 자격 증명이 필요합니다. ClippingMagic.js는 귀하의 사용자에게 API 키를 알려주지 않기 위하여 귀하의 API Id만 사용함에 주의하십시오

보안

모든 요구는 HTTPS에서 행하여야 하며, 모든 요구가 인증되어야 합니다.

성공적인 요구를 하려면 귀하의 HTTP 클라이언트 라이브러리는 서버 이름 표시 (SNI)를 지원하여야 합니다. 이상한 핸드셰이크 에러를 받으면, 대부분이 이러한 이유입니다.

백엔드 대 프론트엔드

모든 업로드 및 다운로드 작동은 백엔드에서 일어나지만, 모든 검토 및 편집 작동은 스마트 편집기에서 일어납니다.

이 분리 작업은 귀하의 API 키를 보호하며, 귀하의 사이트에서 매끄러운 최종-사용자 경험을 가능하게 합니다.

비율 제한

API 사용에는 관대한 허용하에 비율 제한이 있으며 귀하의 API 크레딧 이상의 상한 제한이 없습니다.

정상적 최종 사용자 중심 작동중에는 비율 제한을 거의 받지 않을것입니다, 그 이유는 사용이 줄어용자 중심 작동중에는 비율 제한을 거의 받지 않을것입니다, 그 이유는 사용이 줄어드는 경향이 있으며 서비스가 적절히 처리되는 방향으로 흘러갑니다.

하지만, 최대 5개의 스레드로 시작하고, 원하는 레벨의 평행에 도달할 때 까지, 매5분마다 1개의 스레드를 추가하기를 추천합니다. 100개 이상의 동시 스레드가 필요하면 시작하기 전에 알려주십시오.

너무 많은 요구를 제출하면 429 Too Many Requests를 받기 시작합니다. 이러한 일이 발생하며, 선형적으로 물러나십시오: 처음 이러한 반응을 받으면, 다음 요구를 제출하기 전에 5초를 기다리십시오. 2번째의 연속적 429 반응을 받으면, 다음 요구를 제출하기 이전에 2*5=10 초를 기다리십시오. 3번째 반응을 받으면, 3*5=15 초, 등을 기다리십시오.

요구가 성공적이면, 물러나기를 재설정하시고 매 스레드에 기존하여 물러나십시오 (예, 스레드가 서로 독립적으로 작동하여야 합니다).

오류 JSON 개체

우리는 API 요청의 성공 또는 실패를 알려주기 위하여 기본 HTTP 상태를 이용하며 또한 반환된 오류 JSON 매체에 중요한 에러 정보를 포함합니다.

문제가 있는 요구에는 언제나 오류 JSON 개체를 반환하려고 합니다. 하지만, 내부 서버 실패가 비-JSON 오류 메시지로 나타나는 것은 항상 이론적으로 가능합니다.

특성

status디버깅에 도움이 되도록 응답의 HTTP 상태가 여기 다시 되풀이됩니다.
codeClipping Magic 내부 오류 코드
message디버깅에 유용한 사람이 읽을 수 있는 오류 메시지.

귀하 요구의 HTTP 상태가 200 이면, 오류 JSON 개체가 반환되지 않으며, 요구가 널리 전달되었다고 생각하여도 안전합니다.

일부 HTTP 클라이언트 라이브러리는 400 에서 599 범위로 HTTP 상태 예외를 알려줍니다. 이러한 예외를 감지하고 적절히 처리하여야 합니다.

HTTP Status의미
200-299

성공

400-499

요구에서 제공된 정보에 문제가 있습니다 (예, 매개변수가 없음) 오류 메시지를 검토하고 어떻게 수정할 것인지 알아보십시오.

500-599

Clipping Magic-내부 오류가 있었습니다. 잠시 기다리신 다음 다시 시도하십시오, 그리고 문제가 계속되면 이메일을 저희한테 보내주십시오.

오류 응답 예

{
  "error" : {
    "status" : 400,
    "code" : 1006,
    "message" : "Failed to read the supplied image. "
  }
}

이미지 JSON 개체

이미지 기록이 JSON 개체로 균일한 방법으로 표현되며, 여러가지의 API 행동으로 반환됩니다.

특성

id

이미지를 위한 고유 식별자 사용자에게 편집을 하고 결과를 다운로드할 수 있다고 알려줄 필요가 있습니다.

secret

이 이미지를 ClippingMagic.js로 편집하는데는 필요한 비밀 키

resultRevision

다운로드할 수 있는 가장 최근 개정 번호를 의미하는 번호 (0 는 아직 사용할 수 있는 결과가 없음).

항상 귀하가 이전에 다운로드한 것보다 더 새로운 결과가 있는지 결정할 수 있게 합니다.

originalFilename

원본 이미지를 업로드할 때 파일이름을 포함하는 문자열

test

true는 이것이 자유로이 다운로드할 수 있는 시험 이미지이지만 결과에는 워터마크가 있습니다.

false는 이것이 처리하는데 크레딧이 필요한 생산 이미지이지만 결과에는 워터마크가 없습니다.

{
  "id" : 2345,
  "secret" : "image_secret",
  "resultRevision" : 0,
  "originalFilename" : "image.jpg",
  "test" : false
}

업로드 POST https://clippingmagic.com/api/v1/images

이미지를 업로드하려면, 표준 HTTP POST 파일 업로드를 합니다. 엔드포인트는 귀하의 백엔드에서 호출하여야합니다, 귀하의 웹페이지의 자바스크립트로 호출할 수 없습니다. 이진수 파일을 업로드할 때 콘텐츠-유형multipart/form-data가 되어야 함을 주의하십시오.

추적 변수

입력 이미지는 다음의 한 종류이어야 합니다:

image
이진수

이진수 파일

image.base64
문자열

Base64로 인코딩된 문자열

image.url
문자열

가져올 URL.

.bmp, .gif, .jpeg, .png 또는 .tiff 파일이어야 합니다.

최대 이미지 크기(= 폭 × 높이)는 33,554,432 픽섹이며, 아래의 maxPixels로 무시되지 않으면 4,194,404 픽셀로 축소됩니다. 업로드하기 이전에 나중 숫자 또는 그 이하로 미리-축소하십시오.

test
부울
true, false

이것이 시험 이미지임을 표시하기 위하여 true를 패스하십시오.

완제품 이미지를 위하여 false를 생략 또는 전달하십시오.

테스트 이미지들은 무료로 사용할 수 있으나, 그 결과에는 워터마크가 있습니다.

format
열거형
json, result, clipping_path_svg, alpha_mask_png

기본적으로format=json, 자동-클립 결과 및 이미지 JSON 물체가 나타나지 않습니다. 인간 작동 검토 및 ClippingMagic.js를 사용하여 클립을 손질할 필요가 있으면 이를 사용하십시오.

format=result 생성하고 자동-클립 결과를 가져옵니다.

format=clipping_path_svg 자동-클립 결과를 생성하고 클리핑 패스(SVG)를 가져옵니다.

format=alpha_mask_png 자동-클립 결과를 생성하고 알파 마스크(PNG)를 가져옵니다. 알파 마스크는 입력 이미지와 같은 크기를 가집니다. 그것을 입력 이미지에 젹용하는 것은 원하는 결과를 얻지 못하며, 가장자리 가드 및 후광 스크러버가 가장자리 색을 개선하기 때문입니다.

비-JSON 결과를 가져올 때 idsecretx-amz-meta-idx-amz-meta-secret 헤더로 돌아옵니다. 귀하의 결과를 ClippingMagic.js르 이용하여 검토하고 편집할 수 있도록 이를 반드시 저장 하십시오. 반응에 모든 헤더가 포함된것을 보십시오.

이미지 JSON 개체를 갖고 오는 데는 귀하의 계정에 청구되지 않습니다; 생산 결과를 다운로드할 때만 청구됩니다.

maxPixels
정수
1000000에서 8388708까지

이미지를 업로드한 후 최대 이미지 크기(= 폭 × 높이)를 변경하십시오.

기본값: 4,194,404 픽셀

background.color
#RRGGBB
#0055FF

투명한 배경을 생략 또는 사용하십시오.

'#'를 잊지 말고 포함하십시오.

처리 매개 변수를 구성하십시오:

processing.mode
열거형
auto, photo, graphics

귀하의 이미지를 위한 처리 모드를 제어합니다.

기본값: auto

processing.autoClip
부울
true, false

웹 앱에서 이미지를 편집할 때 자동-클립을 활성화 (기본값) 또는 비활성화합니다.

API를 통하여 이미지를 업로드하기를 원하면 비활성화 하십시오, 하지만 그 후 명백한 배경 (있으면)을 제외한 것을 자유-형식 클립핑하십시오.

기본값: true

색상 수준 구성:

colors.auto
부울
true, false

대비 향성을 위하여 색상 수준을 자동 조정.

기본값: false

colors.brightness
정수
-100에서 100까지

출력 이미지의 발기 조정.

기본값: 0

colors.shadows
정수
-100에서 100까지

출력 이미지의 그림자 조정. 양수 값은 더 어두운 그림지를 의미.

기본값: 0

colors.highlights
정수
-100에서 100까지

출력 이미지의 하이라이트 조정. 양수 값은 더 밝은 하이라이트를 의미.

기본값: 0

colors.temperature
정수
-100에서 100까지

출력 이미지의 색상 온도를 조정. 양수 값은 더 따뜻한 색상을 의미.

기본값: 0

colors.saturation
정수
-100에서 100까지

출력 이미지의 채도를 조정. 양수 값은 더 많은 채도를 의미.

기본값: 0

녹색 스크린을 사용하는 것과 같이, 배경에서 색상 제거, 즉 전경에 캐스트를 구성하십시오.

colorCast.auto
부울
true, false

전경에서 제거하기 위하여 배경 색상을 자동적으로 결정합니다.

기본값: false

colorCast.color
#RRGGBB
#A84400

전경에서 제거하기 위한 수동적으로 선정된 배경 색상.

자동 감지를 위하여 생략.

colorCast.foregroundGuard
부동
0.0에서 20.0까지

더 큰 값은 캐스트 색상과 유사하나 제거되는것 보다 더 포화된 실제 전경 색상의 색상 캐스트 제거의 영향을 축소합니다.

기본값: 4.0

화이트 밸런스 구성:

whiteBalance.auto
부울
true, false

화이트 밸런스를 행하기 위하여 사용되는 참조 색상을 자동적으로 결정.

기본값: false

whiteBalance.color
#RRGGBB
#968386

수동적으로 지정한 화이트 밸런스 색상.

자동 감지를 위하여 생략.

마무리 작업을 구성하십시오.

effects.dropShadow
[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]
30 30 25 0.75

상부 그림자 효과를 클립된 결과에 드롭하십시오.

effects.reflection
[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]
0 200 0.5

반영 효과를 클립된 결과에 추가하십시오.

겅계 매개 변수를 구성하십시오.

edges.corners
부울
true, false

코너 가드를 사용 (기본값) 또는 사용하지 마십시오.

edges.smoothing
열거형
smart, fixed

smart (기본값) 또는 fixed다듬기를 사용하십시오.

edges.smoothingLevel
부동
0.0에서 5.0까지

결과에 적용될 다듬기의 정도를 구성하십시오.

기본값 1.0

edges.feathering
열거형
fixed, auto, local

auto (기본값), local, 또는 fixed 페더링을 사용하십시오.

edges.featheringRadiusPx
부동
0.0에서 6.0까지

결과에 적용될 페더링의 정도를 구성하십시오.

기본값: 1.0

edges.offsetPx
부동
0.0에서 10.0까지

결과에 적용될 경계 오프셋을 구성하십시오.

기본값: 0.0

출력을 결과에 맞추십시오.

fit.toResult
부울
true, false

결과에 맞게를 설정 또는 비설정 (기본값)하십시오.

매개 변수의 나머지가 비설정이면 이 색션에서 사실상 무시됩니다.

fit.paddingPercent
부동
0.0에서 35.0까지

맞춰진 결과 주위에 적용할, 결과 크기의 퍼센트로, 패딩.

기본값: 5.0

fit.paddingPixels
정수
0에서 250까지

맞춰진 결과 주위에 적용될 픽셀로 표시된 패딩.

지정되지 않은 경우에는, 퍼센트 패딩이 사용됩니다.

fit.objectSize
열거형
small, medium, large

개체의 합성 크기를 설정할 수 있습니다. 구매자에게 다른 제품에 비교하여 대략적 크기를 느낌을 제공하기 원하는 전자 상거래에 유용합니다.

기본값: large (= 결과의가 크기 조정이 되지 않음)

fit.verticalAlignment
열거형
top, middle, bottom

과도한 수직 공간이 있으면 결과를 어떻게 맞추어야 하는가 지정하십시오.

종횡비 또는 목표 크기 적용으로 인한 과도한 공간을 분배할 때 또한 적용됩니다, 아래를 참조하십시오.

기본값: middle

fit.shadows
열거형
ignore, pad, tight

그림자를 무시하고, 그림자가 양쪽에 균일하게 여유를 주던가 또는 그림자를 차단하지 않게 하기 위하여 필요한 곳에만 여유를 줄 수 있습니다.

기본값: pad

fit.rotationDeg
부동
-360.0에서 360.0까지

이미지를 회전. 양수 값은 반 시계 방향.

기본값: 0

결과 크기 및 종횡비를 조절합니다.

result.aspectRatio
[width:float, >0]:[height:float, >0]
4:3

결과가 제공된 종횡비가 있도록 확인합니다.

fit.verticalAlignment는 과대한 수직 공간이 어떻게 분배되는지 제어합니다.

기본값: 적용 않됨

result.targetSize
[width:int, >0] [height:int, >0]
400 300

결과에 제공된 크기가 있는지 확인합니다.

fit.verticalAlignment는 과대한 수직 공간이 어떻게 분배되는지 제어합니다.

기본값: 적용 않됨

result.allowEnlarging
부울
true, false

결과가 입력 이미지보다 더 크게 될 수 있는지 없는지 제어합니다.

기본값: false

출력 옵션을 제어합니다.

output.dpi
정수
1에서 4000까지

DPI 정보를 결과에 포함 시킵니다.

결과가 웹 최적화 되었으면 DPI 정보가 포함되지 않습니다.

기본값: 72

output.colorSpace
열거형
sRGB, AdobeRGB, AppleRGB, ColorMatchRGB

색상 공간 정보를 결과에 포함 시킵니다.

결과가 웹 최적화 되었으면 색상 공간 정보가 포함되지 않습니다.

기본값: sRGB

output.jpegQuality
정수
1에서 100까지

JPEG 결과를 만들 때 품질 설정을 구성하십시오.

기본값: 75

output.pngOptimization
열거형
none, lossless, lossy

PNG 결과의 웹 최적화를 구성하십시오.

기본값: lossless

output.jpegOptimization
열거형
none, enabled

JPEG 결과의 웹 최적화를 구성합니다.

기본값: enabled

output.opaqueFileFormat
열거형
jpeg, png

불투명한 결과를 사용하기 위하여 파일 형태를 구성합니다.

기본값: jpeg

구독하지 않고 테스트 모드로 이미지를 업로드할 수 있습니다. 하지만, 업로드하는데 크레딧을 사용하지 않아도 되지만, API를 통하여 생산 이미지를 업로드하기 위하여 유효한 API 구독이 필요합니다.

시도해 보십시오


형태: '#RRGGBB'



형태: '#RRGGBB'

형태: '#RRGGBB'


형태: '[xOffsetPx:int] [yOffsetPx:int] [blurRadiusPx:int, 0 to 75] [opacity:float, 0 to 1]
예: 30 30 25 0.75

형태: '[yOffsetPx:int, 0 to 400] [heightPx:int, 0 to 800] [opacity:float, 0 to 1]
예: 0 200 0.5




형태: '[width:float, >0]:[height:float, >0]
예: 4:3

형태: '[width:int, >0] [height:int, >0]
예: 400 300

Username = API Id, Password = API Key

cURL

$ curl "https://clippingmagic.com/api/v1/images" \
 -u 123:[secret] \ 
 -F 'image=@example.jpg' \ 
 -F 'test=true'

'example.jpg'가 있다고 가정하십시오. 필요시 대치하십시오. 'test=true'가 있는 라인은 선택적.

반응 예

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

다운로드 GET https://clippingmagic.com/api/v1/images/[imageId]

결과를 다운로드하기 위하여, 표준 HTTP GET을 합니다. 결과가 먼저 생성되어야 합니다.

시험 결과는 자유로이 다운로드할 수 있으나, 워터마크가 있습니다. 생산 결과는 처음 다운로드하였을떄는 한 크레딧이 요구되며; 연속적 다운로드는 무료입니다.

사용할 결과가 없으면, 오류 반응을 받습니다.

추적 변수

imageId

URL에 포함됨

업로드 호출에서 반환된 id 값을 삽입하여야 합니다.

선택적
format

format=result (기본값) 결과 이미지를 갖고 옴.

format=clipping_path_svg 대신 클리핑 패스(SVG)를 가져옵니다.

format=alpha_mask_png 대신 알파 마스크(PNG)를 가져옵니다.

format=json 대신 이미지 JSON 물체를 가져옵니다. resultRevision을 검사하기를 원하거나, 또는 이미지 비밀을 잃었을 때 유용합니다.

이미지 JSON 개체를 갖고 오는 데는 귀하의 계정에 청구되지 않습니다; 생산 결과를 다운로드할 때만 청구됩니다.

반응 헤더

formatjson가 아닌 경우, 이 HTTP 응답 헤더에 주요 정보를 제공합니다.

x-amz-meta-id
Example: 2345

귀하 이미지의 id.

x-amz-meta-secret
Example: image_secret

귀하 이미지의 secret.

x-amz-meta-resultrevision
Example: 1

귀하가 본 요청으로 갖고온 resultRevision.

새로운 결과가 생성될 때 마다 이 카운터가 증가됩니다.

x-amz-meta-width
Example: 3200
(format=result에만 포함됨)

본 요청이 갖고온 픽셀로 표시된 결과의 폭.

x-amz-meta-height
Example: 2400
(format=result에만 포함됨)

본 요청이 갖고온 픽셀로 표시된 결과의 높이.

Content-Disposition
Example: attachment; filename*=UTF-8''image_clipped_rev_0.png

확장명을 포함한 결과 파일 이름.

Username = API Id, Password = API Key

cURL

$ curl "https://clippingmagic.com/api/v1/images/2345" \
 -u 123:[secret] \ 
 -LOJ

JSON 응답 예

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

목록 GET https://clippingmagic.com/api/v1/images

이미지 JSON 개체 목록을 갖고 오려면 표준 HTTP GET을 행합니다.

추적 변수

선택적
limit

가져올 기록 숫자. 20로 기본값이 됨 (최소 1, 최대 100).

선택적
offset

기록 목록에서 사용할 오프셋 (기본값 0).

반응 특성

images

이미지 JSON 개체의 배열

limit

limit는 결과를 생산하는데 실제 사용됩니다.

offset

offset는 결과를 생산하는데 실제 사용됩니다.

Username = API Id, Password = API Key

cURL

$ curl "https://clippingmagic.com/api/v1/images?limit=2&offset=0" \
 -u 123:[secret]

반응 예

{
  "images" : [ {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }, {
    "id" : 2346,
    "secret" : "image_secret2",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  } ],
  "limit" : 2,
  "offset" : 0
}

제거 POST https://clippingmagic.com/api/v1/images/[imageId]/delete

이미지를 제거하기 위하여, delete-URL에 표준 HTTP POST를 합니다.

많은 HTTP 클라이언트 라이브러리가 HTTP DELETE 동사를 지원하지 않는 현실을 처리하는데 표준 REST 습관으로부터 약간 이탈된 것이며, 동시에 같은 결과를 내는데 많은 방법의 사용을 피합니다.

추적 변수

imageId

URL에 포함됨

업로드 호출에서 반환된 id 값을 삽입하여야 합니다.

반응 특성

image

제거된 이미지 JSON 개체

시도해 보십시오

Username = API Id, Password = API Key

cURL

$ curl "https://clippingmagic.com/api/v1/images/2345/delete" \
 -u 123:[secret] \ 
 -X POST

반응 예

{
  "image" : {
    "id" : 2345,
    "secret" : "image_secret",
    "resultRevision" : 0,
    "originalFilename" : "image.jpg",
    "test" : false
  }
}

계정 GET https://clippingmagic.com/api/v1/account

구독 상태 및 남아 있는 크레딧과 같은 귀하의 계정 정보를 알아본다

추적 변수

없음

반응 특성

subscriptionPlan

귀하가 현재 구독한 구독 플랜 또는 "없음".

subscriptionState

현재 구독 상태 ('유효' 또는 '연체') 또는 구독하고 있지 않으면 '종료'.

credits

귀하의 계정에 남아있는 크레딧 숫자. 현재 구독하고 있지 않으면 0.

Username = API Id, Password = API Key

cURL

$ curl "https://clippingmagic.com/api/v1/account" \
 -u 123:[secret]

반응 예

{
  "subscriptionPlan" : "none",
  "subscriptionState" : "ended",
  "credits" : 0
}