Posts
SocFlow API를 사용하면 Instagram, Threads 등 여러 소셜 미디어 플랫폼에 게시물을 자동으로 작성하고 발행할 수 있습니다. 타입에 맞는 엔드포인트를 선택하면, 한 번의 요청으로 여러 계정에 동시에 게시할 수 있습니다.
게시물은 텍스트, 이미지, 비디오 등 다양한 형식을 지원합니다. 일부 타입은 예약 발행을 지원하며(예: 피드/릴스/텍스트), 스토리는 플랫폼 특성상 예약 발행을 지원하지 않습니다.
게시물 발행은 비동기로 처리되며, 큐에 추가된 후 순차적으로 처리됩니다.
피드 게시물 생성
일반 피드 게시물(이미지/비디오)을 생성합니다. 캐러셀(다중 미디어)도 지원합니다. 미디어 파일은 사전에 업로드되어 있어야 합니다.
지원 플랫폼
- Instagram: 지원
- Threads: 지원
워크플로우
- 미디어 업로드:
/v1/media엔드포인트로 이미지/비디오 업로드 - 미디어 ID 확인: 업로드 응답에서
media_asset_id추출 - 계정 ID 확인:
/v1/accounts/social엔드포인트로 연동된 계정 조회 - 피드 게시물 생성: 이 엔드포인트로 발행 요청
제약 사항
- 공통
- 제목(title): 필수 (1~100자)
- 내부적으로 제목은 게시물 작업의 제목으로 사용되며, 일부 플랫폼(예: YouTube) 발행 시에도 사용될 수 있습니다.
- 내용(content): 최대 2,000자
- 해시태그(hashtags): 최대 30개
- 제목(title): 필수 (1~100자)
- Instagram
- 미디어 개수: 1~10개
- 미디어 크기(최대): 이미지 8MB / 비디오 100MB
- 조합 규칙: FEED_POST에 동영상이 포함되면 자동으로 REELS로 변환될 수 있습니다.
- Threads
- 미디어 개수/조합:
- 이미지만: 2~20개 (최소 2개 필요)
- 동영상만: 1개
- 이미지+동영상 혼합: 불가
- 미디어 크기(최대): 이미지 50MB / 비디오 100MB
- 미디어 개수/조합:
미디어 옵션
- Name
media.media_asset_ids- Type
- string[]
- Description
필수. 업로드된 미디어 파일의 ID 배열 (UUID 형식)
- Name
media.container_id- Type
- string
- Description
(선택) 컨테이너 ID (UUID 형식)
- Name
media.smart_transform- Type
- object
- Description
(선택) 스마트 이미지 변형 옵션. 생략 시 기본값은
enabled: false입니다.- Name
enabled- Type
- boolean
- Description
필수. 스마트 이미지 변형 활성화 여부.
true로 설정하면 이미지가 자동으로 변형됩니다. 기본값:false
- Name
aspect_ratio- Type
- '1:1' | '4:5'
- Description
필수 (enabled가 true일 때). 이미지 비율.
1:1(정사각형) 또는4:5(세로형) 중 선택 가능합니다.
smart_transform은 선택 사항이며, 생략하거나 enabled: false로 설정하면 스마트 변형이 적용되지 않습니다.
enabled: true로 설정하면, 이미지가 지정한 비율(1:1 또는 4:5)로 자동 변형됩니다.
이 기능은 이미지 품질을 유지하면서 플랫폼에 최적화된 비율로 조정합니다.
요청 본문에 포함된 accounts 중에서, 선택한 타입을 지원하지 않는 플랫폼 계정은
내부적으로 제외될 수 있습니다. 최종적으로 처리 가능한 계정이 하나도 없으면
오류(4000)가 반환됩니다.
curl --location 'https://api.socflow.app/api/v1/posts/feed' \
--header 'X-Secret-Token: {API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"title": "피드 게시물 제목",
"content": "피드 게시물 예시입니다!",
"hashtags": ["SocFlow", "feed"],
"media": {
"media_asset_ids": [
"550e8400-e29b-41d4-a716-446655440000",
"550e8400-e29b-41d4-a716-446655440001"
],
"smart_transform": {
"enabled": true,
"aspect_ratio": "1:1"
}
},
"accounts": ["acc_instagram_12345"]
}'
릴스 생성
릴스(짧은 비디오 콘텐츠)를 생성합니다.
지원 플랫폼
- Instagram: 지원
- Threads: 지원하지 않음
제약 사항
- 미디어: 정확히 1개 (비디오만 가능)
- 내용(content): 최대 2,200자
- 해시태그(hashtags): 최대 30개
- 길이 제한: 플랫폼 정책에 의해 제한될 수 있습니다 (예: 최대 90초)
- 미디어 크기(Instagram): 비디오 최대 300MB
curl --location 'https://api.socflow.app/api/v1/posts/reels' \
--header 'X-Secret-Token: {API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"content": "릴스 예시입니다!",
"hashtags": ["SocFlow", "reels"],
"media": {
"media_asset_ids": ["550e8400-e29b-41d4-a716-446655440010"]
},
"accounts": ["acc_instagram_12345"]
}'
스토리 생성
24시간 후 만료되는 스토리를 생성합니다.
지원 플랫폼
- Instagram: 지원
- Threads: 지원하지 않음
제약 사항
- 미디어: 정확히 1개 (이미지 또는 비디오)
- 내용(content): 최대 500자
- 해시태그(hashtags): 최대 10개
- 예약 발행(scheduled_at): 지원하지 않습니다
- 미디어 크기(Instagram): 이미지 최대 8MB / 비디오 최대 100MB
curl --location 'https://api.socflow.app/api/v1/posts/stories' \
--header 'X-Secret-Token: {API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"content": "스토리 예시입니다",
"hashtags": ["SocFlow"],
"media": {
"media_asset_ids": ["550e8400-e29b-41d4-a716-446655440020"]
},
"accounts": ["acc_instagram_12345"]
}'
텍스트 게시물 생성
미디어 없이 텍스트만으로 게시물을 생성합니다. 전달한 accounts 중에서 선택한 타입을 지원하지 않는 플랫폼 계정은 처리되지 않을 수 있으며, 최종적으로 처리 가능한 계정이 없으면 오류가 반환됩니다.
지원 플랫폼
- Threads: 지원
- Instagram: 지원하지 않음
제약 사항
- 미디어: 없음
- 내용(content): 필수
- API 검증: 최대 2,000자
- 플랫폼(Threads) 정책: 최대 500자 (초과 시 플랫폼 정책에 의해 실패할 수 있습니다)
- 해시태그(hashtags): 최대 30개
curl --location 'https://api.socflow.app/api/v1/posts/text' \
--header 'X-Secret-Token: {API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"content": "텍스트 게시물 예시입니다!",
"hashtags": ["SocFlow", "text"],
"accounts": ["acc_threads_67890"]
}'
공통 응답/오류
모든 Posts 엔드포인트는 아래 공통 응답 형식을 사용합니다.
{
"success": true,
"message": "포스팅 작업 요청 완료"
}
타입별 제약 비교
| 엔드포인트 | 미디어 수 | 미디어 타입 | content 길이 | hashtags | 예약 발행 |
|---|---|---|---|---|---|
POST /v1/posts/feed | 1~20 | 이미지/비디오 | 2000 | 30 | ✅ (scheduled_at) |
POST /v1/posts/reels | 1 | 비디오 | 2200 | 30 | ✅ (scheduled_at) |
POST /v1/posts/stories | 1 | 이미지/비디오 | 500 | 10 | ❌ |
POST /v1/posts/text | 0 | - | 2000 | 30 | ✅ (scheduled_at) |
위 표의 미디어 수/조합은 API 요청 스키마의 상한(예: feed 최대 20) 을 기준으로 요약한 값입니다. 실제 허용 범위는 플랫폼별로 다릅니다. 예: Instagram FEED는 최대 10개, Threads FEED는 이미지 2~20개 또는 동영상 1개(혼합 불가).
사용 예시
전체 워크플로우
async function uploadAndPost() {
// 1. 이미지 업로드
const formData = new FormData()
formData.append('file', imageFile)
const uploadResponse = await fetch('https://api.socflow.app/api/v1/media', {
method: 'POST',
headers: {
'X-Secret-Token': process.env.SOCFLOW_API_KEY,
},
body: formData,
})
const uploadResult = await uploadResponse.json()
const mediaId = uploadResult.data.id
// 2. 게시물 발행
const postResponse = await fetch(
'https://api.socflow.app/api/v1/posts/feed',
{
method: 'POST',
headers: {
'X-Secret-Token': process.env.SOCFLOW_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
content: '새로운 게시물입니다!',
hashtags: ['SocFlow'],
media: {
media_asset_ids: [mediaId],
},
accounts: ['acc_instagram_12345'],
}),
},
)
const postResult = await postResponse.json()
console.log('게시물 발행 요청:', postResult.message)
}
여러 계정에 동시 게시
async function postToMultipleAccounts() {
const mediaId = '550e8400-e29b-41d4-a716-446655440000'
const accounts = ['acc_instagram_12345', 'acc_threads_67890']
const response = await fetch('https://api.socflow.app/api/v1/posts/feed', {
method: 'POST',
headers: {
'X-Secret-Token': process.env.SOCFLOW_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
content: '두 플랫폼에 동시에 게시합니다!',
media: {
media_asset_ids: [mediaId],
},
accounts: accounts,
}),
})
const result = await response.json()
console.log(`${accounts.length}개 계정에 게시 요청 완료`)
}
게시물 발행은 큐 시스템을 통해 처리되므로, 실제 발행까지 몇 분이 소요될 수 있습니다. 발행 상태는 SocFlow 대시보드에서 확인하세요.