주제·본문·링크로 카드뉴스를 만들고, 완성된 장을 그대로 발행하세요.

Posteady가 장마다 문구를 쓰고 디자인한 뒤 각 장을 JPEG 이미지로 만들어 미디어 라이브러리에 저장합니다. 생성은 요청 하나로 끝나지 않습니다. 접수하고, 완성될 때까지 상태를 확인한 다음, 받은 이미지로 발행합니다.

흐름

(선택) 옵션 조회로 쓸 템플릿과 브랜드의 ID를 확인합니다.
생성 접수 — carouselId를 바로 돌려받습니다.
상태 확인 — completed 또는 failed가 될 때까지 20~30초 간격으로 조회합니다.
완성된 장의 mediaId로 발행하거나 예약합니다.

보통 1~~3분 안에 끝납니다. 주제로 만든 5~~6장짜리는 1분 안팎이었고, 장 수가 많거나 링크 자료·AI 이미지를 쓰면 더 걸립니다.

생성 접수

requestId는 직접 생성한 UUID입니다. 내용의 출처는 topic, text, url 중 하나만 지정합니다.

curl --request POST "https://www.posteady.com/api/v1/carousels" \
  --header "Authorization: Bearer $POSTEADY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "requestId": "77777777-7777-4777-8777-777777777777",
  "topic": "처음 카페를 여는 사장님이 개업 첫 달에 자주 하는 실수 다섯 가지",
  "slideCount": 5,
  "language": "ko"
}'

{
  "carouselId": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
  "status": "queued"
}

접수되면 HTTP 202입니다. 잘못된 입력, 요금제, 크레딧 부족, 없는 템플릿이나 브랜드처럼 호출하는 쪽에서 고칠 수 있는 문제는 접수 단계에서 바로 오류로 돌아옵니다.

출처	넣는 값	쓰임
`topic`	한 문장 또는 몇 문장(최대 1,000자)	주제만 주고 내용은 Posteady가 씁니다.
`text`	기사, 메모, 대본 같은 글	준 글을 장으로 나눠 정리합니다.
`url`	공개 링크	페이지의 글과 이미지를 읽어 자료로 씁니다.

선택 항목	설명
`templateId`	템플릿의 디자인을 그대로 두고 문구만 새로 씁니다. 생략하면 Posteady가 디자인합니다.
`brandId`	브랜드 이름과 로고를 장에 넣습니다. 생략하면 브랜드 없이 만듭니다.
`slideCount`	3~20장. 생략하면 Posteady가 정합니다.
`aspectRatio`	`1:1`, `4:5`(기본값), `9:16`, `3:4`, `16:9`. 템플릿을 쓰면 템플릿의 비율을 따르므로 함께 쓸 수 없습니다.
`language`	출력 언어. 생략하면 워크스페이스 언어입니다.
`imageMode`	`stock`(기본값) 스톡 사진, `ai` AI 이미지, `none` 사진 없음, `preserve` 템플릿의 이미지 유지. `none`은 템플릿 없이만, `preserve`는 템플릿과 함께만 씁니다.
`imageStyle`	AI 이미지의 스타일. `imageMode`가 `ai`일 때만 씁니다.
`webImageSearch`	내용에 나오는 제품·인물·장소의 사진을 웹에서 찾습니다. 템플릿과 함께 쓸 수 없습니다.
`instructions`	어조, 대상 독자, 강조할 점 같은 추가 지시(최대 1,000자).

크레딧

카드뉴스 한 개를 만들 때마다 조직 크레딧이 차감됩니다. 금액은 옵션 조회의 generationCredits로 확인하세요. imageMode가 ai이면 생성한 이미지마다 추가로 차감됩니다.

접수할 때 크레딧이 모자라면 402 INSUFFICIENT_CREDITS가 돌아오고 아무것도 만들어지지 않습니다. 접수된 뒤 생성이 실패하면 생성 크레딧은 환불됩니다.

상태 확인

curl --request GET "https://www.posteady.com/api/v1/carousels/cccccccc-cccc-4ccc-8ccc-cccccccccccc" \
  --header "Authorization: Bearer $POSTEADY_API_KEY"

`status`	뜻	다음 동작
`queued`, `processing`	생성 중	20~30초 뒤 다시 조회합니다.
`completed`	저장과 이미지 생성이 끝남	`images`의 `mediaId`로 발행합니다.
`failed`	실패	`error.code`를 확인합니다.

{
  "carouselId": "cccccccc-cccc-4ccc-8ccc-cccccccccccc",
  "status": "completed",
  "editorUrl": "https://www.posteady.com/carousel/cccccccc-cccc-4ccc-8ccc-cccccccccccc",
  "title": "카페 창업 첫 달 실수 5가지",
  "caption": "오픈 첫 달에는 예상치 못한 운영 착오가 생기기 쉽습니다.",
  "aspectRatio": "4:5",
  "slideCount": 5,
  "images": [
    {
      "mediaId": "dddddddd-dddd-4ddd-8ddd-dddddddddddd",
      "url": "https://media.posteady.com/media/example/slide-01.jpg",
      "width": 1080,
      "height": 1350
    }
  ]
}

images는 장 순서대로 들어 있습니다. editorUrl을 열면 Posteady 편집기에서 문구와 디자인을 고칠 수 있습니다. 편집기에서 고친 뒤에는 images가 비어 있을 수 있습니다. 이전 이미지는 고친 내용과 다르기 때문입니다. 편집기에서 다운로드하거나 게시물 만들기를 눌러 이미지를 다시 만든 뒤 조회하세요.

Posteady 앱에서 만든 카드뉴스도 조회할 수 있습니다. carouselId는 편집기 주소의 마지막 부분입니다.

템플릿과 브랜드

curl --request GET "https://www.posteady.com/api/v1/carousels/options" \
  --header "Authorization: Bearer $POSTEADY_API_KEY"

templates의 templateId와 brands의 brandId를 생성 요청에 넣습니다. 기본은 Posteady가 제공하는 템플릿이고, templateSource=workspace를 붙이면 이 워크스페이스에 저장한 템플릿을 조회합니다. nextTemplateCursor가 있으면 cursor로 넘겨 다음 페이지를 읽습니다.

발행으로 잇기

완성된 장은 워크스페이스 미디어 라이브러리의 이미지입니다. mediaId를 순서대로 Instagram 미디어 요청의 items에 넣고, 원하면 caption을 게시물 본문으로 쓰세요. Instagram 캐러셀은 한 번에 2~10장까지 받으므로 10장이 넘는 카드뉴스는 발행할 장을 골라야 합니다.

curl --request POST "https://www.posteady.com/api/v1/posts" \
  --header "Authorization: Bearer $POSTEADY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "accountIds": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "instagram": {
    "requestId": "33333333-3333-4333-8333-333333333333",
    "contentType": "FEED",
    "caption": "오픈 첫 달에는 예상치 못한 운영 착오가 생기기 쉽습니다.",
    "items": [
      {
        "mediaId": "dddddddd-dddd-4ddd-8ddd-dddddddddddd"
      },
      {
        "mediaId": "eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee"
      }
    ]
  }
}'

발행 요청의 requestId는 생성 요청의 것과 별개입니다. 발행 결과는 발행 상태 조회로 확인하세요. 계정과 형식별 입력은 Instagram 미디어 가이드에 있습니다.

다시 보내기

응답을 받지 못했다면 같은 requestId와 같은 본문으로 다시 보내세요. 같은 카드뉴스가 돌아오고 다시 차감되지 않습니다. 같은 requestId에 다른 본문을 보내면 409 REQUEST_CONFLICT입니다.

failed로 끝난 요청을 같은 requestId로 다시 보내면 실패한 결과가 그대로 돌아옵니다. 새로 만들려면 새 requestId를 쓰세요.

실패했을 때

`error.code`	뜻과 대처
`SOURCE_UNAVAILABLE`	링크를 읽지 못했거나 쓸 글이 없습니다. 주소를 확인하거나 내용을 `text`로 보내세요.
`SOURCE_TOO_LONG`	자료가 카드뉴스 한 개에 담기에 너무 깁니다. 줄여서 새로 요청하세요.
`TEMPLATE_UNAVAILABLE`	템플릿이 지워졌거나 바뀌었거나, 이 워크스페이스에 없는 글꼴·이미지가 필요합니다. 다른 템플릿을 고르세요.
`INSUFFICIENT_CREDITS`	접수 뒤 크레딧이 모자라졌습니다.
`PLAN_REQUIRED`	조직의 요금제에 카드뉴스 생성이 포함되지 않습니다.
`RATE_LIMITED`	짧은 시간에 링크를 너무 많이 읽었습니다. 몇 분 뒤 새로 요청하세요.
`STORAGE_LIMIT_EXCEEDED`	워크스페이스 저장 공간이 찼습니다. 미디어 라이브러리를 정리하세요.
`GENERATION_FAILED`, `GENERATION_INTERRUPTED`	생성이 실패했거나 중단됐습니다. 새 `requestId`로 다시 요청하세요.
`RENDER_FAILED`	카드뉴스는 저장됐지만 이미지를 만들지 못했습니다. `editorUrl`에서 마무리하세요.

RENDER_FAILED를 뺀 모든 실패는 생성 크레딧이 환불됩니다. RENDER_FAILED는 카드뉴스가 저장된 상태라 환불되지 않습니다.

알아 둘 점

자료의 동영상은 정지 이미지로 들어갑니다. 동영상이 들어간 장은 Posteady 앱에서 만듭니다.
워크스페이스에 없는 업로드 글꼴을 쓰는 템플릿은 API로 생성할 수 없습니다. 앱에서는 대체 글꼴을 고를 수 있습니다.
MCP에서는 같은 흐름을 create_carousel, get_carousel, list_carousel_options 도구로 씁니다. MCP 도구 안내를 참고하세요.

카드뉴스 생성 레퍼런스 · 재시도 안내 · 오류 코드

카드뉴스 만들기

흐름