HTTP API

기존 HTTP API로 인증하고 도구를 찾으며 변경 사항을 확인하세요.

제품 API 요청은 https://influence.so와 같이 신뢰할 수 있는 Influence 원본 주소로 보내세요. 문서 도메인은 제품 API 요청을 받지 않습니다. 아래의 정확한 경로를 쿼리 매개변수 없이 사용하세요.

권한 범위가 지정된 API 키 만들기

Influence 설정에서 앱 및 자동화 → API 키를 여세요. 필요한 권한과 만료 시점을 선택하세요. 1번만 표시되는 키를 비밀 저장소에 PUBLISH_API_TOKEN으로 보관하세요. Authorization: Bearer …로 전송하고 URL, 요청 본문 또는 채팅에 넣지 마세요. 더 이상 필요하지 않으면 폐기하세요.

도구 검색 및 계정 조회

PUBLISH_API_URL을 신뢰할 수 있는 원본 주소로 설정하세요. 다음 예시는 프로세스에 이미 PUBLISH_API_TOKEN이 있다고 가정합니다. accountList에는 integrations:read가 필요합니다. 추가 페이지를 가져오려면 해당 페이지네이션 필드를 따르세요.

export PUBLISH_API_URL="https://influence.so"
curl "$PUBLISH_API_URL/api/v1/tools" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN"

curl "$PUBLISH_API_URL/api/v1/tools/accountList/call" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"input":{}}'

요청 경로

메서드	경로	용도
`GET`	`/api/v1/tools`	이 인증 정보로 사용할 수 있는 도구를 나열합니다.
`POST`	`/api/v1/tools/{tool}/call`	승인된 업로드 후속 작업을 포함해 확인이 필요 없는 도구를 호출합니다.
`POST`	`/api/v1/tools/{tool}/prepare`	실행하지 않고 정확한 변경 작업을 준비합니다.
`POST`	`/api/v1/tools/{tool}/confirm`	준비된 변경 작업을 확인합니다.
`POST`	`/api/v1/media/import`	준비된 소용량 바이너리 이미지 업로드를 확인합니다.

JSON 도구 요청은 Content-Type: application/json과 input만 포함한 본문인 {"input":{…}}를 사용합니다. 도구별 입력 스키마는 현재 도구 카탈로그에서 확인하세요.

작업 준비 및 확인

카탈로그의 confirmation 필드를 사용하세요. 조회에는 보통 확인이 필요 없지만 인사이트 새로고침은 조회임에도 확인이 필요합니다. 업로드 파트 조회, 완료 및 취소는 이미 승인된 업로드를 /call로 이어 갑니다.

정확한 업무 입력을 /prepare로 보내세요. 성공 응답에는 status: "confirmation_required", confirmationCapability, expiresAt, inputDigest 및 선택적 summary가 포함됩니다.
만료되기 전에 같은 입력을 /confirm으로 보내세요. 반환된 확인 권한 값을 X-Publish-Confirmation에 넣고, 호출자가 새로 생성한 키를 Idempotency-Key에 넣으세요.
입력, 확인 권한 값 및 키를 함께 보관하세요. 확인 도중 중단되거나 결과가 불확실하면 같은 요청에 이 3가지를 모두 다시 사용하세요. 불확실한 결과를 복구하려고 대체 작업을 새로 준비하지 마세요.

멱등성 키는 A–Z, a–z, 0–9, ., _, :, - 중에서 고른 문자 16–200개로 구성합니다. 확인 권한 값은 내부 의미를 해석하지 않는 비밀 값입니다. /call이나 /prepare에 키를 보내도 확인된 변경 작업이 예약되지는 않습니다.

전송 확인은 게시 승인과 별개입니다. 게시 또는 일정 변경 시에는 계정, 문구, 설정, 실제 미디어 미리보기 또는 링크, 예약 시각 및 시간대를 포함한 현재 검토 내용을 모두 보여 주세요. 해당되는 소셜 텍스트·이미지·동영상 검토에 대해 클라이언트는 사람이 새로 명시적으로 승인했음을 approval: "approved"로 보고할 수 있습니다. 동의를 지어내거나 준비를 승인으로 다뤄서는 안 됩니다. Influence는 이를 클라이언트가 보고한 승인으로 기록합니다. 지원되는 임베디드 카드나 로그인한 검토 화면은 사람이 한 동작을 직접 기록합니다.

TikTok Direct는 검토 절차를 통해 채팅에서 명시한 선택과 동의를 받습니다. 전체 선택을 campaignReview로 저장한 다음 실행 전에 갱신된 검토에 대한 새 승인을 받으세요. 검토 카드는 선택 사항입니다. 일반 API/CLI 예약은 AI 예약 허용량을 사용하지 않습니다. 별도의 MCP 및 Influence IQ 허용량은 저장된 AI 검토를 나중에 Influence에서 승인하더라도 해당 절차에 적용됩니다. 요금제와 서비스 제공업체의 다른 요건도 계속 적용됩니다. 추가 작업 전에 저장된 처리 기록을 읽으세요. needs_review이면 다시 보내지 말고 상태를 대조해 확인해야 합니다.

오류 및 불확실한 결과 처리

HTTP 상태와 응답 본문을 모두 확인하세요. 도구 성공 응답은 {"ok":true,"toolName":"…","output":{…}}입니다. 도구 실패 응답은 {"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}}이며 HTTP 200으로 올 수도 있습니다. 전송 실패는 ok나 toolName 없이 {"error":{"code":"…","message":"…","retryable":false}} 형식을 사용합니다.

401은 인증이 필요하다는 뜻이므로 만료 또는 폐기 여부를 확인하세요. 권한이 없으면 요청을 반복할 것이 아니라 적절한 권한을 받아야 합니다. 503은 서비스 이용 불가 또는 다른 예약 요청이 워크스페이스를 갱신 중임을 뜻할 수 있습니다. 반환된 오류 코드와 재시도 안내를 따르고 게시 작업을 자동으로 다시 실행하지 마세요. 시간 초과만으로 변경 실패가 입증되지는 않습니다. 확인 데이터를 유지하고 현재 상태를 읽은 뒤 다시 제출하세요. 접수, 예약 및 게시 완료는 서로 다른 결과입니다.

미디어 업로드

로컬 파일에는 SDK의 uploadMedia 또는 CLI의 media:upload를 우선 사용하세요. 같은 멀티파트 업로드 도구를 사용하며 재시도용 clientKey를 유지합니다. assetId가 있는 준비 완료 결과만 첨부할 수 있습니다. 접근 권한이 있는 HTTPS 링크는 mediaImport에 url과 선택적 name을 넣어 사용하세요. 실제 호스트 파일 참조는 별도의 file 객체를 사용합니다. 공개 URL에 호스트 파일 ID를 지어낼 필요는 없습니다. 로컬 파일 경로는 다운로드 URL이 아닙니다. 미디어 제한을 확인하세요. 직접 업로드로 더 큰 준비 완료 MP4가 허용되더라도 HTTPS 동영상 가져오기는 250 MiB로 제한됩니다.

POST /api/v1/media/import는 기존 소용량 이미지 전송을 지원합니다. 정확한 업로드 설명자로 mediaImport를 준비한 다음 같은 바이트를 application/octet-stream으로 보내세요. X-Publish-Confirmation, Idempotency-Key 및 URI 인코딩된 JSON 설명자를 담은 X-Publish-Upload를 포함하세요. 바이트는 설명자의 크기 및 SHA-256과 일치해야 합니다. 이 전송은 3 MiB로 제한되므로 더 큰 지원 파일에는 업로드 도우미를 사용하세요. 업로드는 게시를 승인하지 않습니다.

API 참조 살펴보기 또는 OpenAPI 명세 다운로드.