help-icon
icon

Public API 사용 안내

helpDetails-time-icon2026-09-23T15:37:56+08:00

개인 API 키로 기기, 프록시와 앱을 조회하고 초기화, 기존 프록시 연결 및 설치를 요청합니다. 고객용 여섯 API는 https://api.foxphone.com의 /public_api/v1을 사용합니다.

API 목록

HTTP/public_api/v1설명
GET/phones기기 조회
GET/proxies프록시 조회
POST/phones/actions/reset일괄 초기화
POST/proxies/{proxy_id}/bind기존 프록시 연결
GET/apps앱 및 버전 조회
POST/phones/actions/install-app일괄 앱 설치

API 키 준비

아바타의 Settings에서 개인 센터 API Key를 엽니다. 계정당 유효 키 하나이며 재생성하면 기존 키는 즉시 무효, 전체 값은 한 번만 표시됩니다. 모든 요청에 X-API-Key, POST에 Content-Type: application/json을 보냅니다. 웹 JWT, Cookie, Device-ID, hash, platform은 필요 없으며 Bearer로 대체할 수 없습니다.

X-API-Key: <your_api_key>

키는 서버 환경 변수나 비밀 저장소에만 보관하며 프런트엔드, 공개 저장소나 클라이언트에 넣지 마세요. URL, 본문, 로그나 문의에 쓰지 않습니다. 예제는 API_KEY를 사용합니다. 유출 시 즉시 재생성/비활성화하고 모든 호출자를 갱신합니다.

export API_KEY="<your_api_key>"

공통 규칙 및 응답

HTTPS를 사용합니다. 성공은 HTTP 200 및 data 안의 내용, 실패는 4xx/5xx와 문자열 reason입니다. message뿐 아니라 상태, reason과 항목별 결과를 확인합니다. 오류 data는 null일 수 있고 request_id를 보관합니다. 파트너 /open_api/v1 인증과 별도입니다.

같은 키는 분당 60회 한도를 공유합니다. page_num/page_size 생략 또는 양수가 아니면 1/20, page_size>100은 400입니다. 기기/프록시는 search, 앱은 app_name. pod_ids는 공백, 빈 항목과 중복 제거 후 1–100개 문자열 배열이며 순서 대신 pod_id로 대응합니다.

pod_id는 항상 문자열입니다. proxy_id, total, 버전 id와 version_code는 JSON 숫자이므로 특히 JavaScript에서 큰 정수를 무손실 처리합니다. 0과 빈 문자열은 유지되며 빈 목록은 [] 또는 null입니다.

{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "total": 0,
    "phones": []
  },
  "message": "success"
}

기기 조회

자신의 기기를 이름 또는 pod_id의 search로 조회합니다. data.phones에 pod_id, name, online_status, operating_status, proxy_id가 있고 data.total은 개수입니다. proxy_id=0은 미연결이며 로컬 연결은 클라우드 적용 완료 증거가 아닙니다.

online_status: 0 부팅 중, 1 실행 중, 2 꺼짐, 3 종료 중, 4 재시작, 5 스트리밍, 6 스트림 준비. operating_status: 0 부팅, 1 실행, 2 꺼짐, 3 종료, 4 재시작, 5 초기화. 6은 미정의이며 두 필드는 다릅니다.

필드유형
pod_idstring
namestring
online_statusinteger
operating_statusinteger
proxy_idnumber
curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones?page_num=1&page_size=20&search=example" \
  -H "X-API-Key: ${API_KEY}"
{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "total": 1,
    "phones": [
      {
        "pod_id": "pod-example-001",
        "name": "test-phone",
        "online_status": 1,
        "operating_status": 1,
        "proxy_id": 42
      }
    ]
  },
  "message": "success"
}

프록시 조회

이름/ID로 프록시를 찾습니다. data.proxies에 proxy_id, name, proxy_type, proxy_ip, proxy_port, check_status. 포트는 문자열이며 인증 정보나 갱신 URL은 반환하지 않습니다. 상태는 unchecked, success, failed, 과거 데이터는 빈 값일 수 있습니다. 이전 성공이 현재 가용성을 보장하지 않습니다.

curl --fail-with-body "https://api.foxphone.com/public_api/v1/proxies?page_num=1&page_size=20&search=example" \
  -H "X-API-Key: ${API_KEY}"
{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "total": 1,
    "proxies": [
      {
        "proxy_id": 42,
        "name": "example-proxy",
        "proxy_type": "socks5",
        "proxy_ip": "203.0.113.42",
        "proxy_port": "1080",
        "check_status": "success"
      }
    ]
  },
  "message": "success"
}

일괄 초기화

초기화는 데이터를 지우므로 백업하고 대상을 확인합니다. pod_ids만 보내며 자기 소유의 실행 중이고 조작 가능한 기기여야 합니다. 꺼짐, 초기화 중, 충돌 기기는 거절됩니다. phone_template_mode(0 포함), phone_template_id(빈 값 포함)는 400 / PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED. 모델은 무작위이고 대안 없으면 템플릿 미지정. 시뮬레이션을 보존하고 이전 프록시는 검사 후 복원을 시도하며 새 프록시를 구매/선택하지 않습니다.

curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones/actions/reset" \
  -H "X-API-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"pod_ids":["pod-example-001"]}'

기존 프록시 연결

목록의 양의 proxy_id를 경로에 쓰고 본문에는 pod_ids만 보냅니다. 자기 리소스이며 프록시가 유효하고 만료 전, 새 검사 통과가 필요합니다. 꺼진 기기는 설정만 저장하고 다음 부팅에 적용합니다. 실행 중은 비동기 적용으로 재부팅할 수 있습니다. 충돌은 거절하며 무효 프록시는 409 / BATCH_PRECHECK_FAILED, 항목 PRECHECK_FAILED입니다.

curl --fail-with-body "https://api.foxphone.com/public_api/v1/proxies/42/bind" \
  -H "X-API-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"pod_ids":["pod-example-001"]}'

일괄 결과 및 오류

초기화/연결만 successful_pod_ids/failed_items를 사용합니다. 전체 사전 검사 실패는 409의 data.failed_items이며 최상위 metadata가 아닙니다. 일부 수락 후 시스템 간 롤백은 불가합니다. 성공 목록은 수락/저장이지 완료가 아니며 null일 수 있습니다. 전체 배치를 재전송하지 마세요.

{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "successful_pod_ids": [
      "pod-example-001"
    ],
    "failed_items": [
      {
        "pod_id": "pod-example-002",
        "code": "PROVIDER_REJECTED",
        "message": "provider rejected the operation"
      }
    ]
  },
  "message": "success"
}
{
  "request_id": "example-request-id",
  "code": 409,
  "data": {
    "failed_items": [
      {
        "pod_id": "pod-example-002",
        "code": "PHONE_NOT_RUNNING",
        "message": "phone is not running"
      }
    ]
  },
  "message": "batch precheck failed",
  "reason": "BATCH_PRECHECK_FAILED"
}
필드설명
RESOURCE_NOT_OWNED현재 계정 소유의 리소스가 아닙니다
RESET_IN_PROGRESS기기를 초기화하는 중입니다
OPERATION_IN_PROGRESS충돌하는 작업이 진행 중입니다
PHONE_NOT_RUNNING기기가 실행 중이 아닙니다
RESOURCE_UNAVAILABLE리소스가 없거나 사용할 수 없습니다
PRECHECK_FAILED프록시 확인 또는 다른 사전 검사에 실패했습니다
PROVIDER_REJECTED클라우드 제공자가 요청을 거부했거나 제출에 실패했습니다

앱 및 버전 조회

조회 source는 필수 official 또는 user. app_name과 선택 정수 app_type, 공통 페이지 규칙을 사용합니다. package_name으로 묶고 total은 앱 수입니다. 패키지는 오름차순, versions는 version_code 내림차순. 설치는 package_name/version_code이며 version_id/version_name이 아닙니다. 기기 설치 목록이 아닙니다.

curl --fail-with-body "https://api.foxphone.com/public_api/v1/apps?source=official&page_num=1&page_size=20&app_name=example" \
  -H "X-API-Key: ${API_KEY}"
{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "total": 1,
    "apps": [
      {
        "app_id": "app-example",
        "app_name": "Example App",
        "package_name": "com.example.app",
        "app_type": 1,
        "icon_url": "",
        "source": "official",
        "versions": [
          {
            "id": 101,
            "version_id": "version-example",
            "version_name": "1.0.0",
            "version_code": 100
          }
        ]
      }
    ]
  },
  "message": "success"
}

일괄 앱 설치

비어 있지 않은 package_name, 양의 정수 version_code와 유효 pod_ids가 필요합니다. 자신의 켜진 기기를 선택하고 source를 명시하세요. 생략/빈 값은 개인 후 공식 검색, 명시하면 다른 소스로 대체하지 않습니다. APK URL은 미지원. data.items의 pod_id/job_id는 제출만 뜻합니다. 설치 결과 조회나 초기화/연결 같은 전체 상태 검사 응답 규약은 없습니다.

curl --fail-with-body "https://api.foxphone.com/public_api/v1/phones/actions/install-app" \
  -H "X-API-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"source":"official","package_name":"com.example.app","version_code":100,"pod_ids":["pod-example-001"]}'
{
  "request_id": "example-request-id",
  "code": 200,
  "data": {
    "items": [
      {
        "pod_id": "pod-example-001",
        "job_id": "job-example-001"
      }
    ]
  },
  "message": "success"
}

오류 및 재시도

400은 인수 수정, 401/403은 키/계정, 409는 충돌 해소, 429는 백오프합니다. 조회는 한도 내 재시도 가능. 쓰기에는 공개 멱등 키가 없어 timeout/500 후 먼저 수락 상태를 확인합니다. 앱 없음, 버전 불일치나 제출 실패도 500 / PUBLIC_API_INTERNAL_ERROR일 수 있어 미실행 증거가 아닙니다.

HTTPreason
400INVALID_ARGUMENT
400PHONE_TEMPLATE_PARAMETER_NOT_SUPPORTED
401INVALID_API_KEY
403API_KEY_DISABLED
403USER_ACCOUNT_UNAVAILABLE
409BATCH_PRECHECK_FAILED
429RATE_LIMIT_EXCEEDED
500PUBLIC_API_INTERNAL_ERROR
500PUBLIC_API_AUTH_ERROR

API 키 보안

키는 서버 환경 변수나 비밀 저장소에만 보관하며 프런트엔드, 공개 저장소나 클라이언트에 넣지 마세요. URL, 본문, 로그나 문의에 쓰지 않습니다. 예제는 API_KEY를 사용합니다. 유출 시 즉시 재생성/비활성화하고 모든 호출자를 갱신합니다.

검증 및 지원

문의에는 request_id, 경로, HTTP, reason, 시간과 가린 인수를 주고 키는 보내지 마세요. 조회부터 검증한 뒤 허가된 테스트 기기에서 쓰기를 수행하고 결과 확인 후 규모를 늘립니다.

관련 문서

Email contact
Cookie notification icon쿠키 알림
이 웹사이트는 사용자 경험을 개선하기 위해 쿠키를 사용합니다. 쿠키 정책에 대해 자세히 알아보거나 동의를 철회하려면 개인정보 보호정책 및 쿠키 정책를 확인하세요.