Bài đăng

​

Chọn endpoint theo loại media

​

Số ảnh mỗi bài

​

Phân phối với platforms[]

curl -X POST https://api.madiad.com/v1/posts/photos \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Idempotency-Key: 9f1c2e7a-4b6d-4e2a-9c10-7b3f8d5a1e22" \
  -F "profile_id=9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83" \
  -F "platforms[]=instagram" \
  -F "platforms[]=facebook" \
  -F "platforms[]=tiktok" \
  -F "caption=New blend dropping today" \
  -F "photos[]=@./launch.jpg"

​

Đăng ảnh bằng URL

curl -X POST https://api.madiad.com/v1/posts/photos \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3ab77c14-08e5-4d69-b2f1-6c5904ad7e83" \
  -d '{
    "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
    "platforms": ["instagram", "facebook"],
    "caption": "New blend dropping today",
    "photo_urls": [
      "https://cdn.example.com/launch-1.jpg",
      "https://cdn.example.com/launch-2.jpg"
    ]
  }'

• Mỗi URL phải là link ảnh trực tiếp, công khai, dùng https:// (hostname, không dùng địa chỉ IP). Link trang chia sẻ mở ra một trang web (ví dụ trang xem của drive) sẽ bị từ chối kèm thông báo lỗi rõ ràng. Hãy dùng URL file trực tiếp. Redirect được theo tối đa 5 bước, nhưng mọi bước đều phải là https://.
• Tối đa 40 URL mỗi request, 30 MB mỗi ảnh và tổng 120 MB.
• Cũng dùng được trong multipart: gửi photo_urls[] dưới dạng field text, và trộn thoải mái với photos[] dạng file trong cùng một request. Với carousel, file tải lên đứng trước, rồi tới ảnh từ URL, mỗi nhóm theo thứ tự gửi.

​

Ghi đè theo từng nền tảng

  -F "caption=New blend dropping today" \
  -F "instagram_caption=New blend dropping today ☕ #specialtycoffee" \
  -F "x_caption=New blend out now →"

​

Giới hạn ký tự

• caption dài quá giới hạn của nền tảng nào thì chỉ bị cắt cho riêng nền tảng đó. Các nền tảng khác vẫn nhận caption đầy đủ, và request không bị từ chối. Quy tắc này áp cho tiêu đề (YouTube, Pinterest, Reddit, bài ảnh TikTok), cho phần thân bài (Instagram, LinkedIn, Google Business, video TikTok, Mastodon), và cho phần mô tả lấy từ caption (Pinterest 500, YouTube 5.000 byte, bài ảnh TikTok 4.000). Tiêu đề được gộp thành một dòng; thân bài giữ nguyên xuống dòng. Chỗ cắt rơi vào cuối một từ nếu vẫn giữ được ít nhất 60% giới hạn, không bao giờ cắt đôi emoji, và kết thúc bằng một dấu ”…”.
• Phản hồi cho biết đã cắt những gì. Mảng truncated liệt kê từng nền tảng và phần chữ bị cắt (text: title, caption hoặc description), kèm length của caption và limit. Nền tảng nào không có trong danh sách thì đã nhận đủ caption. Muốn tự chọn nội dung, hãy đặt trường riêng của nền tảng đó: <platform>_caption (hoặc <platform>_title), hay các trường mô tả trong bảng trên.
• Nội dung bạn đặt riêng cho một nền tảng thì không bao giờ bị cắt. <platform>_title hay <platform>_caption bạn gửi được đăng đúng như bạn viết. Vì vậy, nếu nó dài quá giới hạn của nền tảng đó, request bị từ chối kèm lỗi nêu rõ trường. Các trường mô tả bạn tự đặt (description, pinterest_description, youtube_description, tiktok_description) cũng được gửi đúng như bạn viết, và không được kiểm tra độ dài trước khi đăng.
• Một ngoại lệ: bài Instagram (và bài ảnh, video Google Business hoặc Mastodon) vào hàng đợi. Phần chữ đã cắt cho Instagram đi trong một job Instagram riêng (xem ghi chú ở trên), và với bài ảnh, video thì Google Business và Mastodon cũng vậy. Vì thế request có add_to_queue, chọn một trong hai nền tảng này cùng các nền tảng khác và caption dài quá giới hạn của nó sẽ bị từ chối. Hãy rút ngắn caption, hoặc đưa nền tảng đó vào hàng đợi bằng một request riêng. Nếu chỉ đưa riêng nền tảng đó vào hàng đợi thì caption vẫn được cắt và xếp lịch bình thường.
• Trên dashboard MADIAD Hub, bộ đếm dưới ô Nội dung đo theo giới hạn thấp nhất trong các nền tảng bạn đã chọn. Chưa chọn nền tảng nào thì bộ đếm đo theo mọi nền tảng đã kết nối với profile. Ngay dưới đó là danh sách nền tảng sẽ bị cắt, cắt còn bao nhiêu ký tự. Đây chỉ là thông báo; bài vẫn đăng bình thường. Trình soạn bài còn cho bạn chọn viết một nội dung riêng cho từng nền tảng, thay vì một caption chung (“Riêng từng nền tảng”). Khi đó mỗi nền tảng đã chọn có một ô riêng và được gửi nội dung trong ô đó. Hub không cắt chữ này, trừ một trường hợp: với bài Pinterest, bài YouTube và bài ảnh TikTok, ô tiêu đề để trống sẽ được điền một tiêu đề cắt từ chính nội dung của nền tảng đó. Nội dung vượt giới hạn cứng của nền tảng sẽ bị từ chối kèm tên ô trước khi gửi đi, và ô để trống cũng bị từ chối. Ô của Mastodon được gửi đúng như đã gõ, giống mastodon_caption.
• Facebook, X, Threads và Bluesky không bao giờ bị cắt. X, Threads và Bluesky tự tách văn bản dài thành chuỗi bài, giới hạn của Facebook là 63.206, còn Telegram và Discord tự cắt ở phía họ.
• Phần ghi đè theo từng nền tảng được kiểm tra, với những nền tảng có giới hạn cứng: Instagram, LinkedIn, TikTok, YouTube, Reddit, Pinterest và Google Business. Một <platform>_title (hoặc <platform>_caption) vượt giới hạn (ví dụ tiktok_title > 90 cho bài ảnh, reddit_title > 300, hay instagram_caption > 2.200) sẽ bị báo lỗi rõ ràng trước khi đăng. X, Threads và Bluesky không kiểm trước vì chúng tự tách thành chuỗi bài thay vì từ chối; Telegram và Discord thì cắt bớt; còn ghi đè cho Facebook chỉ bị giới hạn ở Reels. Những trường hợp này được gửi thẳng tới nền tảng và tự báo kết quả riêng.
• Link trên X. Mọi URL mà X biến thành liên kết bấm được sẽ bị gỡ khỏi bài X trước khi đăng. Hãy để link trong hồ sơ hoặc trong ảnh/video.

​

Tùy chọn nâng cao theo nền tảng

​

Bình luận đầu tiên (first comment)

  -F "caption=New blend dropping today" \
  -F "first_comment=Mua ngay tại 👉 link trong bio" \
  -F "instagram_first_comment=Bấm link trong bio ☕ #specialtycoffee"

• X và Threads: đăng dưới dạng reply cho bài. Với bài X tự tách chuỗi, nó reply vào tweet cuối của chuỗi.
• YouTube: đăng thành bình luận cấp cao nhất dưới video.
• Instagram: chỉ áp dụng cho bài ảnh và video (Instagram không có bài chỉ văn bản).

  -F "first_comment=Bộ ảnh chi tiết bên dưới 👇" \
  -F "first_comment_media[]=@./detail-1.jpg" \
  -F "first_comment_media[]=@./detail-2.jpg"

​

Caption sinh bằng AI

  -F "autogenerate=true" \
  -F "autogenerate_language=vi"

​

Yêu cầu của từng nền tảng

​

Đọc response

{
  "status": "processing",
  "profile_id": "9f2b4c17-8e3a-4d5f-b061-2c7e9a4d1b83",
  "platforms": ["instagram", "facebook", "tiktok"],
  "request_id": "req_01HZX9H6S8T0V2W4X6Y8Z0A2B4",
  "job_id": null,
  "results": null
}

• completed: mọi nền tảng đã đăng bài, results chứa kết quả theo từng nền tảng. Ở response của lệnh đăng, trạng thái này nghĩa là tất cả đã trả lời ngay.
• processing: đã được tiếp nhận và đang được đăng; đây là câu trả lời đầu tiên thông thường với mọi loại bài. Poll bằng request_id, hoặc đăng ký webhooks.
• scheduled: đã lên lịch cho thời điểm tương lai, poll bằng job_id. job_id chỉ có ở bài gửi để đăng sau: đó là id dùng để hủy hoặc dời bài.
• partial: một số nền tảng đã đăng thành công và ít nhất một nền tảng bị từ chối, kiểm tra từng mục trong results.
• draft: không nền tảng nào từ chối, nhưng ít nhất một nền tảng nhận bài vào mục nháp của tài khoản thay vì đăng, nên ở đó bài chưa hiện công khai. Thường gặp nhất là TikTok: khi tài khoản chạm giới hạn đăng trực tiếp trong ngày của TikTok, bài vào hộp thư của ứng dụng TikTok và chờ chủ tài khoản bấm đăng. Mục của nền tảng đó trong results có "draft": true, success: true và không có url. Đây là kết quả cuối: đừng gửi lại, gửi lại chỉ thêm một bản nháp nữa.
• failed: tất cả nền tảng nhắm tới đều từ chối bài đăng. Mã HTTP vẫn là 200, lý do theo từng nền tảng nằm trong results.
• canceled: bài hẹn giờ bạn đã hủy trước khi nó chạy. Không có gì được đăng, results là null, và trạng thái này không đổi nữa. Lệnh đăng không bao giờ trả trạng thái này; lệnh tra trạng thái và lịch sử bài đăng thì có.
• unknown: chưa xác định được kết quả trong thời gian chờ (trả về HTTP 502 với mã upstream_timeout). Bài có thể đã lên, đừng retry ngay. Câu trả lời có kèm request_id: tra trạng thái bằng mã đó sẽ nhận unknown cho tới khi phía nền tảng nhận được bài, sau đó là processing rồi kết quả. Xem Lỗi và Idempotency.

{
  "results": {
    "instagram": { "success": true, "publish_id": "17912345678901234", "url": "https://instagram.com/p/abc123" },
    "tiktok":    { "success": false, "error": "You have reached the daily posting cap on tiktok. Used 15/15 in the last 24 hours. · Tạm dịch: Bạn đã đạt giới hạn đăng bài trong ngày trên TikTok. Đã dùng 15/15 trong 24 giờ qua.", "error_code": "daily_cap_reached" }
  }
}

​

Cảnh báo: bài đã lên nhưng chưa đúng hẳn như yêu cầu

{
  "status": "completed",
  "results": { "tiktok": { "success": true, "url": "https://www.tiktok.com/@shop/photo/7401" } },
  "warnings": [
    { "platform": "tiktok", "code": "music_not_applied", "message": "Bài được nhận nhưng KHÔNG gắn nhạc: …" }
  ]
}

• warnings chỉ xuất hiện khi có ít nhất một cảnh báo. Bài không có cảnh báo thì không có khoá warnings.
• code là music_not_applied (chỉ TikTok: kết nối lại TikTok cho Profile đó), first_comment_skipped (first_comment không được đăng, ví dụ vì bài được lưu nháp) hoặc platform_warning (lưu ý khác, đọc message). Có thể có thêm mã mới, nên gặp mã lạ thì xử lý như platform_warning.
• platform là null khi lệnh đăng nhiều kênh trả về cảnh báo mà không nêu kênh nào.
• Cảnh báo không có nghĩa là bài lỗi: đừng đăng lại bài chỉ vì một cảnh báo.
• Với bài nhận processing, cảnh báo đến cùng kết quả poll trạng thái, không có ở response đầu tiên của lệnh đăng. Cảnh báo chỉ trả kèm câu trả lời đầu tiên của bài thì chỉ có ở response của lệnh đăng, nên hãy lưu lại từ đó.

​

Video: trả lời ngay, đăng ở chế độ nền

​

Kiểm tra trạng thái sau

curl "https://api.madiad.com/v1/posts/status?request_id=req_01HZX9H6S8T0V2W4X6Y8Z0A2B4" \
  -H "Authorization: Bearer $MADIAD_API_KEY"

​

Bài tài liệu (LinkedIn)

curl -X POST https://api.madiad.com/v1/posts/document \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "'$PROFILE_ID'",
    "platforms": ["linkedin"],
    "document_url": "https://.../ho-so-nang-luc.pdf",
    "caption": "Hồ sơ năng lực 2026",
    "description": "Mười trang, không cần tải về."
  }'

​

Đăng lại phần bị lỗi

curl -X POST https://api.madiad.com/v1/posts/retry \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "request_id": "'$REQUEST_ID'" }'

​

Gỡ bài đã đăng

curl -X POST https://api.madiad.com/v1/posts/unpublish \
  -H "Authorization: Bearer $MADIAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "profile_id": "'$PROFILE_ID'", "platform": "facebook", "post_id": "'$PLATFORM_POST_ID'" }'