Skip to main content
POST
완료된 번역, 립싱크 출력 또는 동적 자막 출력을 본인에게 연결된 채널 하나에 게시하거나 예약합니다. 동영상 URL은 선택한 저장 버전에서 가져옵니다.

인증 및 권한

string
필수
이 헤더에 VoiceCheap API 키를 전달하세요. 동일한 API 키를 사용하는 Authorization: Bearer도 지원합니다. OAuth 액세스 토큰은 MCP에서만 허용되며, 이 REST 엔드포인트에서는 사용할 수 없습니다.
필요한 권한: publishing:write, projects:read. 활성 유료 구독이 필요합니다. 권한은 팀 역할, 리소스 소유권, 미디어 크레딧 또는 요금제 한도를 변경하지 않습니다.

매개변수

string
필수
텍스트 값입니다.최소 길이: 1. 최대 길이: 200. 패턴: ^[^/\\]+$.
string
필수
텍스트 값입니다.최소 길이: 1. 최대 길이: 200. 패턴: ^[^/\\]+$.
string
필수
텍스트 값입니다.최소 길이: 1. 최대 길이: 200. 패턴: ^[^/\\]+$.
string
필수
텍스트 값입니다.허용값: “youtube”, “tiktok”.
string
필수
텍스트 값입니다.최소 길이: 1. 최대 길이: 200. 패턴: ^[^/\\]+$.
string
텍스트 값입니다.허용값: “translated”, “lip-synced”, “dynamic-subtitles”. 기본값: “translated”.
string
필수
텍스트 값입니다.최소 길이: 1. 최대 길이: 100.
string
텍스트 값입니다.최대 길이: 5000.
string
텍스트 값입니다.허용값: “public”, “unlisted”, “private”. 기본값: “private”.
string
텍스트 값입니다.허용값: “PUBLIC_TO_EVERYONE”, “MUTUAL_FOLLOW_FRIENDS”, “FOLLOWER_OF_CREATOR”, “SELF_ONLY”. 기본값: “SELF_ONLY”.
string
텍스트 값입니다.형식: “date-time”. 패턴: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$.
string
전송 계층에서는 선택 사항입니다. 생략하면 서버가 유효성 검사 전에 식별자를 추가합니다. 응답이 유실된 경우 안전하게 복구할 수 있도록 고정된 UUID v4를 직접 제공하세요.형식: “uuid”. 패턴: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$.
아래 JSON Schema는 검색을 통해 제공되는 정확한 필드 이름, 중첩 유형, 기본값, 범위 및 허용값을 유지합니다. 추가적인 필드 간 규칙은 작업 참고 사항에 나와 있습니다.

멱등성

각 변경 작업에 대해 requestId 또는 Idempotency-Key HTTP 헤더에 UUID v4를 사용하세요. 네트워크 오류 후에는 동일한 식별자와 동일한 인수를 재사용하세요. 둘 다 제공하는 경우 값이 일치해야 합니다. 저장된 요청을 재전송해도 작업이 반복되거나 월간 호출이 추가로 차감되지 않습니다. 실패하거나 중단된 요청은 자동으로 다시 시작되지 않습니다. 첫 실행이 일반적으로 동기식인 경우에도, 재시도 시 동일한 요청이 아직 실행 중이면 모든 변경 작업에서 HTTP 202를 반환할 수 있습니다. 실행은 완료되었지만 resultStored가 false이면, 재시도 시 원래 결과 대신 저장된 요청 상태를 HTTP 200으로 반환합니다. 해당 영역의 기록, 결과 또는 다운로드 액션으로 출력을 조회하세요.

요청 예제

예제의 리소스 식별자와 미디어 키를 계정에서 반환된 값으로 바꾸세요. 동일한 변경 작업을 재시도할 때는 요청 식별자를 유지하세요.

응답

이 작업은 실행 중에 HTTP 202를 반환합니다. requestId를 저장하고 해당 식별자와 원래 작업 이름으로 action_request_get을 폴링하세요. 폴링 상태는 running, completed, failed, interrupted입니다. 완료된 결과가 별도의 미디어 작업을 가리킬 수 있으므로 해당 작업의 상태 또는 출력 액션을 이어서 사용하세요. 예약된 게시의 식별 정보 및 타임스탬프 또는 즉시 게시된 동영상의 식별 정보 및 URL을 반환합니다.

결과 필드

scheduledAt이 생략되고 즉시 게시 서비스 호출이 완료됩니다.

즉시 게시 시도 식별 정보와 플랫폼 동영상 정보를 반환합니다.
HTTP 200

이 요청 복구 및 폴링

연결이 끊어진 후에도 동일한 식별자를 사용하세요. resultStored가 false이면 해당 기록, 결과 또는 다운로드 액션을 통해 출력을 조회하세요. 진행 상황을 확인하기 위해 두 번째 생성을 시작하지 마세요.
HTTP 200

작업 참고 사항

  • 이 액션은 외부에 게시합니다. 인증된 요청 주체에 속한 채널 하나를 선택하세요. 팀 프로젝트 미디어에 접근할 수 있어도 다른 구성원의 채널에 접근할 권한은 부여되지 않습니다.
  • videoSource의 기본값은 translated입니다. lip-synced는 가장 최근에 완료된 립싱크 동영상을 선택하고 dynamic-subtitles는 저장된 동적 자막 출력을 선택합니다. 버전은 completed 상태여야 하며 선택한 출력이 존재해야 합니다.
  • 통합의 기본값은 YouTube의 private과 TikTok의 SELF_ONLY입니다. 동영상 URL은 호출자가 전달한 URL이 아니라 권한이 확인된 저장 버전에서 가져옵니다.
  • scheduledAt은 선택 사항입니다. 제공하는 경우 오프셋이 포함된 유효한 ISO 날짜 및 시간이어야 하며 반드시 미래 시각이어야 합니다. 핸들러는 해당 값을 Unix 밀리초 단위로 반환합니다. 생략하면 이 액션은 즉시 게시합니다.
  • 이 액션은 실행 시간이 깁니다. 핸들러 결과는 action_request_get을, 이후 게시 상태는 publishing_list를 폴링하세요. 예약 응답과 즉시 실행 응답은 필드가 다릅니다.
  • 즉시 실행 핸들러는 소셜 게시 서비스가 반환한 videoId 및 선택적 videoUrl과 함께 published 상태를 보고합니다. 대기열에 등록된 예약 응답에는 videoId 또는 videoUrl이 없습니다.
  • TikTok의 경우 최종 숫자 동영상 ID를 사용할 수 없을 때 videoId가 플랫폼 게시 식별자일 수 있으며, videoUrl은 연결된 채널 URL 또는 저장된 원본 동영상으로 대체될 수 있습니다.

사용량

성공한 호출마다 월간 API/MCP 호출 1회가 차감됩니다. 미디어 크레딧과 해당 작업의 생성 허용량도 적용됩니다.

오류