publish_post

pro.aicut/aicut · Verify this server

SENDS a prepared post, or schedules it. THIS IS IRREVERSIBLE: the post goes out under the user's own name and nothing here can take it down. ASK THE USER FIRST, IN THE SAME MESSAGE THAT NAMES WHAT WILL GO OUT: the account, the text, the visibility, and the time if it is scheduled. Wait for their explicit go. A bare 'yes' only counts if your ask for THIS post was the message immediately before it. IF THE PUBLISH CARD ALREADY TOOK THEIR APPROVAL, that message IS the go and it names the post id to use. Call this with that id and nothing else: do not prepare the post again, and do not pass a caption, a visibility or a disclosure - this tool does not accept them, so the caption, the visibility, the disclosures, the account and the video the person set in the card are exactly what goes out. THE ONE THING YOU CAN STILL CHANGE IS THE TIME: `schedule_at` here overrides whatever the card staged, so passing it - or passing null to send a scheduled post immediately - publishes at a time the person did not approve. Do not touch it unless they have asked you to, in this conversation, since they confirmed. Then poll `get_post_status`; the card is watching the same post and will show what the platform says. WHEN: after `prepare_post`, once the user has chosen and confirmed. WHAT IT ANSWERS IS NEVER `posted`, AND THAT IS NOT A DELAY - it is the truth. TikTok answers `publishing`: the platform took the job and now downloads the video itself, which can still fail. YouTube and Instagram answer `submitted`: aicut's own poster has the job and nothing has confirmed anything at all - it is a weaker statement than `publishing`, deliberately. A scheduled post answers `scheduled`. In every case poll `get_post_status` until it reads `posted` or `failed`, and never tell the user their video is live on the strength of this call. SCHEDULING: pass `schedule_at` to set or move the time, or `schedule_at: null` to send a post now that was prepared for later. A scheduled TikTok or Instagram post waits in aicut and our scheduler fires every due post at once - which is why a schedule can be REFUSED with `retry_after_seconds` meaning 'move it at least this many seconds later', not 'wait this long'. A scheduled YouTube post is uploaded immediately as private and YouTube publishes it; after that aicut does not ask YouTube about it again, so it stays `scheduled` with a `post_id` you can hand the user. THE POSTING LIMITS, SO YOU CAN PACE A BATCH INSTEAD OF DISCOVERING THEM: per CONNECTED ACCOUNT, tiktok 5/min and 13/24h, youtube 2/min and 10/24h, instagram 4/min and 25/24h. BOTH WINDOWS ARE ROLLING, not calendar - the 24h one does not reset at midnight, so the 14th TikTok post waits until the oldest of the 13 falls out of the window. Two connected accounts on the same platform each get their own allowance. Over the limit you get a 429 (`post_rate_limited` or `daily_post_limit`) carrying `retry_after_seconds`: respect it, do not retry sooner, and do not prepare a second post or use a second account to get around it. WHAT DOES NOT CONSUME A POST, because a slot is only taken by a call that actually reaches the platform: every refusal raised BEFORE that point is free. That is all of them except a 429 - a 400, a 404, a 409 (`already_published`, `post_expired`, `consent_required`, `video_not_ready`), a 403 `insufficient_scope`, and on TikTok a dead connection or an unreadable file found in preflight. Fix one of those and retry at once; you have lost nothing. `prepare_post` is a separate meter again (5/min, 100/24h per connected account) and preparing never spends a publish. SCHEDULING SPENDS THE SAME ALLOWANCE, counted around the time you ask for rather than around now - aicut's scheduler fires every due post at once, so a minute holding its cap is refused at the WRITE. That is why a schedule refusal's `retry_after_seconds` means 'move it at least this many seconds later', not 'wait this long'. REFUSALS you act on: 403 `insufficient_scope` = THE USER'S CONNECTION CANNOT POST, and this is the common one. Publishing needs the `social:publish` permission, which a connection approved before aicut added it never carries, so a connection that generates videos perfectly well can still be refused here. It is not an outage, not a bad `video_id` or `account_id`, and not something a retry, a different account or a different video fixes. Tell the user, in these terms: aicut can post, but this connection was never given permission to; they disconnect aicut at https://www.aicut.pro/account/settings#connections, connect it again in the app they are using, and approve "Post your videos to your connected social accounts" on the aicut consent screen. Say that disconnecting stops the connection at once, so generating will not work either until they have reconnected - it is a minute of downtime, not a background task. Then STOP; nothing here works again until they have done it. A 403 here posted NOTHING - the request never reached the platform, so say plainly that the video did not go out. OUTPUT: this returns JSON for you to read. When you report back to the user, give them the media URL plus a one-line summary. Do not paste the raw JSON, job ids, or internal field names into the conversation.