API reference

Social posts

Publishes finished generations to a character’s connected accounts, now or at a scheduled time. 1 credit per platform; 3 credits for an X post whose caption contains a link. Platforms that fail are refunded.

The social post object

idstring
pst_ + 32 hex characters.
objectstring
Always social_post.
character_idstring
Publishing character.
platformsstring[]
Requested platforms.
captionstring | null
Caption.
generation_idsstring[]
Published generations.
scheduled_atstring | null
ISO time, when scheduled.
statusstring
published, scheduled, partial (some platforms failed) or failed.
resultsarray
Per platform: platform, success, url, scheduled, error.
creditsinteger
Charged.
refunded_creditsinteger
Refunded for failed platforms.
created_atinteger
Unix ms.

POST/v1/social/posts

Scope: socialIdempotency-Key requiredReturns 201

Uploads the media to each platform and publishes (or schedules). Media: one video generation, or up to 10 image generations (carousel where supported).

Body

character_idstringrequired
Character whose accounts publish.
platformsstring[]required
1–5 of instagram, tiktok, youtube, threads, twitter. Each must be connected.
generation_idsstring[]required
Completed generations: 1 video or 1–10 images.
captionstring
Up to 5,000 characters; trimmed to each platform’s limit.
scheduled_atstring
ISO 8601 with offset, at least 5 minutes ahead. Omit to publish now.
settingsobject
Per-platform options.
- instagramobject
  content_type (feed, story, reel), aspect_ratio (original, 1:1), collaborators (≤3 usernames), user_tags (≤20), thumb_offset (seconds).
- tiktokobject
  allow_comments, allow_duet, allow_stitch, ai_disclosure, auto_add_music (booleans).
- youtubeobject
  content_type (short, community_post), title (≤100), visibility (public, unlisted, private), made_for_kids.

Errors

Code	When
`VALIDATION_ERROR`	Generation not finished, mixed media, or a scheduled time too soon.
`INSUFFICIENT_CREDITS`	Balance too low, or an account’s monthly fee is unpaid.
`NOT_FOUND`	Unknown character or generation.

Request

curl -X POST https://api.oriorai.com/v1/social/posts \
  -H "Authorization: Bearer $ORIOR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "character_id": "Qx8p2LmN4vRt",
  "platforms": [
    "instagram",
    "tiktok"
  ],
  "generation_ids": [
    "gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b"
  ],
  "caption": "Morning ritual ☕️",
  "settings": {
    "instagram": {
      "content_type": "reel"
    },
    "tiktok": {
      "ai_disclosure": true
    }
  }
}'

const response = await fetch('https://api.oriorai.com/v1/social/posts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "character_id": "Qx8p2LmN4vRt",
    "platforms": [
      "instagram",
      "tiktok"
    ],
    "generation_ids": [
      "gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b"
    ],
    "caption": "Morning ritual ☕️",
    "settings": {
      "instagram": {
        "content_type": "reel"
      },
      "tiktok": {
        "ai_disclosure": true
      }
    }
  }),
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os, uuid
import requests

response = requests.post(
    "https://api.oriorai.com/v1/social/posts",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "character_id": "Qx8p2LmN4vRt",
        "platforms": ["instagram", "tiktok"],
        "generation_ids": ["gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b"],
        "caption": "Morning ritual ☕️",
        "settings": {
            "instagram": {
                "content_type": "reel",
            },
            "tiktok": {
                "ai_disclosure": True,
            },
        },
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 201

Response

{
  "id": "pst_1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f",
  "object": "social_post",
  "character_id": "Qx8p2LmN4vRt",
  "platforms": [
    "instagram",
    "tiktok"
  ],
  "caption": "Morning ritual ☕️",
  "generation_ids": [
    "gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b"
  ],
  "scheduled_at": null,
  "status": "published",
  "results": [
    {
      "platform": "instagram",
      "success": true,
      "url": "https://www.instagram.com/p/…",
      "scheduled": false,
      "error": null
    },
    {
      "platform": "tiktok",
      "success": true,
      "url": "https://www.tiktok.com/@ava/video/…",
      "scheduled": false,
      "error": null
    }
  ],
  "credits": 2,
  "refunded_credits": 0,
  "created_at": 1758620000000
}

GET/v1/social/posts

Scope: socialReturns 200

Newest first.

Query parameters

limitintegerdefault: 20
1–100.
cursorstring
next_cursor from the previous page.

Request

curl https://api.oriorai.com/v1/social/posts \
  -H "Authorization: Bearer $ORIOR_API_KEY"

const response = await fetch('https://api.oriorai.com/v1/social/posts', {
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
  },
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os
import requests

response = requests.get(
    "https://api.oriorai.com/v1/social/posts",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "data": [
    {
      "id": "pst_1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f",
      "object": "social_post",
      "character_id": "Qx8p2LmN4vRt",
      "platforms": [
        "instagram",
        "tiktok"
      ],
      "caption": "Morning ritual ☕️",
      "generation_ids": [
        "gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b"
      ],
      "scheduled_at": null,
      "status": "published",
      "results": [
        {
          "platform": "instagram",
          "success": true,
          "url": "https://www.instagram.com/p/…",
          "scheduled": false,
          "error": null
        },
        {
          "platform": "tiktok",
          "success": true,
          "url": "https://www.tiktok.com/@ava/video/…",
          "scheduled": false,
          "error": null
        }
      ],
      "credits": 2,
      "refunded_credits": 0,
      "created_at": 1758620000000
    }
  ],
  "next_cursor": null
}

GET/v1/social/posts/{id}

Scope: socialReturns 200

One post with per-platform results.

Path parameters

idstringrequired
Post ID.

Request

curl https://api.oriorai.com/v1/social/posts/pst_1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f \
  -H "Authorization: Bearer $ORIOR_API_KEY"

const response = await fetch('https://api.oriorai.com/v1/social/posts/pst_1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f', {
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
  },
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os
import requests

response = requests.get(
    "https://api.oriorai.com/v1/social/posts/pst_1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "id": "pst_1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f",
  "object": "social_post",
  "character_id": "Qx8p2LmN4vRt",
  "platforms": [
    "instagram",
    "tiktok"
  ],
  "caption": "Morning ritual ☕️",
  "generation_ids": [
    "gen_7f3c9a1e2b4d4c8f9a0b1c2d3e4f5a6b"
  ],
  "scheduled_at": null,
  "status": "published",
  "results": [
    {
      "platform": "instagram",
      "success": true,
      "url": "https://www.instagram.com/p/…",
      "scheduled": false,
      "error": null
    },
    {
      "platform": "tiktok",
      "success": true,
      "url": "https://www.tiktok.com/@ava/video/…",
      "scheduled": false,
      "error": null
    }
  ],
  "credits": 2,
  "refunded_credits": 0,
  "created_at": 1758620000000
}

Social posts

The social post object

Create a social post

List social posts

Retrieve a social post