{"openapi":"3.0.3","info":{"title":"APICK 틱톡 키워드 영상 검색","version":"1.0.0","description":"키워드·해시태그로 틱톡 영상을 최대 50개까지 검색해 조회수·좋아요·댓글·공유 수와 작성자 정보를 수집합니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/tiktok_search/jobs":{"post":{"summary":"틱톡 키워드 영상 검색","description":"키워드·해시태그로 틱톡 영상을 최대 50개까지 검색해 조회수·좋아요·댓글·공유 수와 작성자 정보를 수집합니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job_id":{"type":"string"},"product":{"type":"string"},"status":{"type":"string"},"max_results":{"type":"integer"},"unit_point":{"type":"integer"},"reserved_point":{"type":"integer"},"charged_point":{"type":"integer"},"result_count":{"type":"integer"},"created_at":{"type":"string"},"completed_at":{"type":"string","nullable":true},"result_expires_at":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"video_id":{"type":"string"},"url":{"type":"string"},"username":{"type":"string"},"description":{"type":"string"},"posted_at":{"type":"string"},"views":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"},"duration_sec":{"type":"integer"},"hashtags":{"type":"array","items":{"type":"string"}},"region":{"type":"string"},"cover_image_url":{"type":"string"},"author":{"type":"object","properties":{"followers":{"type":"integer"},"is_verified":{"type":"boolean"}}}}}},"result_expired":{"type":"boolean"}}},"api":{"type":"object","properties":{"success":{"type":"boolean"},"cost":{"type":"integer"}}}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"keyword":{"type":"string","description":"검색어 또는 해시태그 (예: 캠핑 요리, #캠핑, 1~100자) (string)","example":"캠핑 요리"},"max_results":{"type":"string","description":"최대 결과 수 1~50 (기본 10). 이 수만큼 포인트를 먼저 예약하고 실제 건수만 차감 (string)","example":"10"},"idempotency_key":{"type":"string","description":"응답을 못 받아 다시 보낼 때 같은 접수로 처리할 키(8~128자, 영문·숫자·_.:-) (string)"}},"required":["keyword"]}}}}}},"/rest/scrape_jobs/5f0c2a9e7b1d4c3a8e6f90a1b2c3d4e5":{"get":{"summary":"틱톡 키워드 영상 검색","description":"키워드·해시태그로 틱톡 영상을 최대 50개까지 검색해 조회수·좋아요·댓글·공유 수와 작성자 정보를 수집합니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job_id":{"type":"string"},"product":{"type":"string"},"status":{"type":"string"},"max_results":{"type":"integer"},"unit_point":{"type":"integer"},"reserved_point":{"type":"integer"},"charged_point":{"type":"integer"},"result_count":{"type":"integer"},"created_at":{"type":"string"},"completed_at":{"type":"string","nullable":true},"result_expires_at":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"video_id":{"type":"string"},"url":{"type":"string"},"username":{"type":"string"},"description":{"type":"string"},"posted_at":{"type":"string"},"views":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"},"duration_sec":{"type":"integer"},"hashtags":{"type":"array","items":{"type":"string"}},"region":{"type":"string"},"cover_image_url":{"type":"string"},"author":{"type":"object","properties":{"followers":{"type":"integer"},"is_verified":{"type":"boolean"}}}}}},"result_expired":{"type":"boolean"}}},"api":{"type":"object","properties":{"success":{"type":"boolean"},"cost":{"type":"integer"}}}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/rest/scrape_jobs/{job_id}":{"get":{"summary":"틱톡 키워드 영상 검색","description":"키워드·해시태그로 틱톡 영상을 최대 50개까지 검색해 조회수·좋아요·댓글·공유 수와 작성자 정보를 수집합니다.","security":[{"bearerAuth":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"job_id":{"type":"string"},"product":{"type":"string"},"status":{"type":"string"},"max_results":{"type":"integer"},"unit_point":{"type":"integer"},"reserved_point":{"type":"integer"},"charged_point":{"type":"integer"},"result_count":{"type":"integer"},"created_at":{"type":"string"},"completed_at":{"type":"string","nullable":true},"result_expires_at":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"video_id":{"type":"string"},"url":{"type":"string"},"username":{"type":"string"},"description":{"type":"string"},"posted_at":{"type":"string"},"views":{"type":"integer"},"likes":{"type":"integer"},"comments":{"type":"integer"},"shares":{"type":"integer"},"saves":{"type":"integer"},"duration_sec":{"type":"integer"},"hashtags":{"type":"array","items":{"type":"string"}},"region":{"type":"string"},"cover_image_url":{"type":"string"},"author":{"type":"object","properties":{"followers":{"type":"integer"},"is_verified":{"type":"boolean"}}}}}},"result_expired":{"type":"boolean"}}},"api":{"type":"object","properties":{"success":{"type":"boolean"},"cost":{"type":"integer"}}}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"x-code-tables":[{"title":"Body (data)","columns":["이름","타입","설명"],"rows":[["job_id","String","작업 ID (32자리). 상태·결과 조회에 씁니다"],["product","String","수집 상품 이름"],["status","String","waiting · processing · completed · failed"],["max_results","Integer","요청한 최대 결과 수"],["unit_point","Integer","결과 1건당 포인트(이 작업에 적용된 단가)"],["reserved_point","Integer","현재 예약 중인 포인트. 완료·실패하면 0"],["charged_point","Integer","최종 차감 포인트(완료 시 결과 건수 × 단가)"],["result_count","Integer","받은 결과 수"],["created_at","String","접수 시각 (ISO 8601)"],["completed_at","String","완료 시각. 진행 중이면 null"],["items","Array","수집 결과(완료 시). 각 항목의 필드는 아래 표"],["video_id","String","영상 ID"],["url","String","영상 주소"],["username","String","작성자 사용자명"],["description","String","설명"],["posted_at","String","게시 시각"],["views","Integer","조회수"],["likes","Integer","좋아요 수"],["comments","Integer","댓글 수"],["shares","Integer","공유 수"],["saves","Integer","저장 수"],["duration_sec","Number","영상 길이(초)"],["hashtags","Array","해시태그"],["region","String","지역 코드"],["cover_image_url","String","표지 이미지"],["author","Object","{ followers, is_verified }"],["result_expires_at","String","결과 보관 기한(완료 후 72시간)"],["result_expired","Boolean","보관 기한이 지나 결과를 지웠으면 true"],["error","Object","실패 시 { code, message }"]]},{"title":"오류 코드","columns":["HTTP","error_code","설명"],"rows":[["400","SCRAPE_INPUT_INVALID","입력 형식 또는 max_results 범위 오류. 상류를 호출하지 않으며 포인트는 차감되지 않습니다"],["402","SCRAPE_POINTS_INSUFFICIENT","max_results 만큼의 포인트가 부족합니다"],["403","SCRAPE_PAYMENT_REQUIRED","충전 이력이 있는 계정만 이용할 수 있습니다"],["404","SCRAPE_JOB_NOT_FOUND","작업이 없거나 다른 계정의 작업입니다"],["409","SCRAPE_IDEMPOTENCY_CONFLICT","같은 idempotency_key 로 다른 내용을 접수했습니다"],["429","SCRAPE_TOO_MANY_JOBS","진행 중인 작업이 5개입니다. 끝난 뒤 다시 접수해 주세요"],["503","SCRAPE_TEMPORARILY_UNAVAILABLE","일시적으로 접수하지 못했습니다. 포인트는 차감되지 않습니다"],["작업 실패","TARGET_NOT_FOUND · TARGET_PRIVATE · SCRAPE_TIMEOUT · SCRAPE_FAILED","상태 조회의 error.code. 예약한 포인트는 모두 돌려드립니다"]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}