게시물 발행
연결된 소셜 계정에 텍스트를 발행하거나 미디어 발행 작업을 접수합니다.
curl -X POST "https://example.com/api/v1/posts" \ -H "Content-Type: application/json" \ -d '{ "accountIds": [ "11111111-1111-4111-8111-111111111111" ], "posts": [ "Hello from the Posteady API!" ] }'{ "results": [ { "accountId": "11111111-1111-4111-8111-111111111111", "provider": "threads", "username": "your_brand", "success": true, "postIds": [ "18000000000000001" ] } ], "summary": { "succeeded": 1, "failed": 0 }}Threads, X, LinkedIn에 텍스트를 발행하거나 TikTok, Instagram, YouTube, Facebook에 미디어 발행 작업을 접수합니다. 대상 플랫폼에 맞는 요청 예제를 선택하세요. 모든 계정 ID는 API 키의 워크스페이스에 속해야 합니다.
발행 형식 선택
- 텍스트:
accountIds와posts를 사용합니다. 여러 글은 Threads와 X에서 연속 글로 발행되며 LinkedIn은 글 하나만 허용합니다. - 이미지: Threads·X·LinkedIn 텍스트 요청에
mediaIds를 더합니다. 이미지는 첫 글에 붙습니다. Threads는 120장(2장 이상이면 캐러셀), X는 14장, LinkedIn은 1~20장을 받고 답글은 텍스트 그대로입니다. 플랫폼이 여럿이면 가장 좁은 한도를 적용합니다. Threads·X 연결 글의 답글에도 이미지를 붙이려면 대신mediaIdsByPost에 글마다 목록을 하나씩 넣습니다. - 동영상: Threads는
mediaIds와mediaIdsByPost에 동영상도 받습니다. MP4·MOV 형식에 5분·1 GiB 이하이며, 하나만 붙이거나 캐러셀에 이미지와 섞을 수 있습니다. LinkedIn 글에는 MP4·MOV 형식에 30분·500 MiB 이하 동영상 하나를 다른 미디어 없이 붙입니다. 동영상이 든 요청에는 X 계정을 넣을 수 없습니다. 동영상으로 시작하는 Threads 글과 동영상이 있는 LinkedIn 글은 백그라운드에서 발행하므로 돌려받은jobId로 결과를 확인하세요. - TikTok: 계정 하나와 캡션 하나를 지정하고
posts와video를 함께 사용합니다. - Instagram, YouTube, Facebook: 해당 플랫폼 객체와 계정 하나를 지정합니다.
posts와 다른 발행 형식의 객체는 생략하세요. - 미디어: 파일을 업로드하고 확인을 마친 뒤
mediaId를 사용합니다. 선택한 게시 유형에 맞는 이미지나 동영상을 사용하세요.
X 게시물의 링크
X는 첫 게시물(posts[0])에서 링크를 자동 제거합니다. http://, https://, www.와 foo.com, foo.io/path처럼 프로토콜 없는 도메인이 대상이며 경로·쿼리 문자열·프래그먼트도 함께 제거합니다. 답글인 posts[1] 이후의 링크는 유지하며 같은 요청의 다른 플랫폼에는 원문을 전달합니다. X에 링크를 공유하려면 답글에 직접 넣으세요. 제거한 링크를 답글로 자동 이동하지는 않습니다. 첫 글의 링크를 남기려면 xOptions.keepFirstPostLink를 true로 보내세요. 남긴 주소를 X가 링크로 인식하면 그 글은 링크가 든 글로 크레딧을 받습니다. X 글자 수는 제거 후 검증합니다. 첫 글에 빈 문자열이나 공백만 남으면 어떤 계정에도 발행하기 전에 요청 전체가 VALIDATION_ERROR(HTTP 422)로 실패합니다. 입력과 실제 본문 예제는 X 가이드를 참고하세요.
X 크레딧
X 발행에는 조직 크레딧이 듭니다. 글마다 2, 링크가 든 글은 20이며 스레드는 글마다 따로 셉니다. 첫 글에서 제거한 링크는 세지 않습니다. Posteady는 어떤 계정에도 발행하기 전에 요청의 모든 X 계정 몫을 먼저 받습니다. 크레딧이 모자라면 요청이 INSUFFICIENT_CREDITS(HTTP 402)로 실패하고 아무것도 발행하지 않습니다. 발행되지 않은 글의 크레딧은 돌려줍니다.
결과 확인
텍스트 발행은 계정별 결과를 반환합니다. HTTP 200 응답에서도 각 success 값을 확인하세요. 비동기 작업 접수는 HTTP 202와 results[0].jobId를 반환합니다. 이때 success: true는 접수 성공이며 실제 발행은 GET /api/v1/publish-jobs/{id}로 확인하세요. 글이 2개 이상인 Threads 연결 글은 요청 안에서 첫 글만 발행하고 나머지는 글당 약 10초씩 백그라운드에서 발행합니다. 그 계정의 결과에는 postIds에 첫 글, status: processing, jobId가 있고 응답은 HTTP 202입니다. 답글에 이미지가 있는 X 연결 글(mediaIdsByPost)도 같습니다. 다른 X 연결 글은 요청 안에서 모두 발행합니다. 첫 글에 동영상이 있는 Threads 글은 요청 안에서 아무것도 발행하지 않습니다. Threads가 동영상을 백그라운드에서 처리하므로 그 계정의 결과에는 빈 postIds, status: processing, jobId가 있고 응답은 HTTP 202입니다.
미디어 요청 재시도
동일한 UUID requestId와 변경하지 않은 입력으로 재시도하면 기존 작업을 반환합니다. 같은 ID에 다른 입력을 보내면 REQUEST_CONFLICT가 발생합니다. Facebook은 진행 중인 작업에 HTTP 202, 종료된 작업 재요청에 HTTP 200을 반환하며 failed·canceled·unknown은 success: false입니다. 다른 미디어 플랫폼의 실패한 종료 작업 재요청은 HTTP 502를 반환합니다. 텍스트 요청에는 이 중복 방지 보장이 없습니다.
인증
apiKey 위치: header
요청 본문
application/json
TypeScript 타입
TypeScript에서 request body 타입을 사용하세요.
Threads, X, LinkedIn에는 텍스트를 발행합니다. 공개 TikTok 동영상 하나에는 video, TikTok 사진 게시물 하나에는 tiktokPhoto, Instagram 미디어 게시물 하나에는 instagram, YouTube 동영상 하나에는 youtube, Facebook 페이지 게시물 하나에는 facebook을 사용합니다. TikTok은 posts와 video 또는 tiktokPhoto를 함께 사용합니다. Instagram, YouTube, Facebook은 각각 독립된 발행 형식으로 다른 발행 형식과 함께 보낼 수 없습니다. Threads·X·LinkedIn 텍스트 요청에는 mediaIds 를 더해 첫 글에 라이브러리 이미지를 붙이거나(Threads·LinkedIn 은 동영상도 받습니다), mediaIdsByPost 를 더해 Threads·X 연결 글의 글마다 미디어를 붙일 수 있습니다. 텍스트 요청에는 threadsOptions, xOptions, linkedinOptions를 더할 수 있습니다. 각 옵션은 accountIds 중 그 플랫폼 계정에 적용되며, 그 플랫폼 계정이 없으면 요청이 실패합니다.
Threads, X, LinkedIn에는 텍스트를 발행합니다. 공개 TikTok 동영상 하나에는 video, TikTok 사진 게시물 하나에는 tiktokPhoto, Instagram 미디어 게시물 하나에는 instagram, YouTube 동영상 하나에는 youtube, Facebook 페이지 게시물 하나에는 facebook을 사용합니다. TikTok은 posts와 video 또는 tiktokPhoto를 함께 사용합니다. Instagram, YouTube, Facebook은 각각 독립된 발행 형식으로 다른 발행 형식과 함께 보낼 수 없습니다. Threads·X·LinkedIn 텍스트 요청에는 mediaIds 를 더해 첫 글에 라이브러리 이미지를 붙이거나(Threads·LinkedIn 은 동영상도 받습니다), mediaIdsByPost 를 더해 Threads·X 연결 글의 글마다 미디어를 붙일 수 있습니다. 텍스트 요청에는 threadsOptions, xOptions, linkedinOptions를 더할 수 있습니다. 각 옵션은 accountIds 중 그 플랫폼 계정에 적용되며, 그 플랫폼 계정이 없으면 요청이 실패합니다.
응답 본문
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json