POST
https://www.app.ocoya.com/api/_public/v1/post/ai
Create an AI-generated draft post
curl --request POST \
  --url https://www.app.ocoya.com/api/_public/v1/post/ai \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "prompt": "Write a launch post for our new analytics dashboard.",
  "tone": "professional",
  "postLength": "medium",
  "channelIds": [
    "clh49poxf008x8kov4ncbjty9"
  ],
  "generateImage": true,
  "imageCount": 3,
  "referenceUrls": [
    "https://example.com/reference.png"
  ],
  "referenceDesignIds": [
    "design_123"
  ],
  "studioDesignId": "design_123",
  "studioDesignFields": {
    "pixy-cmte3datf00f435708hleujti": "https://example.com/logo.png"
  }
}
'
{
  "postGroupId": "cmajvvb9q0003ja5vh0538j6r",
  "status": "GENERATING",
  "scheduledAt": null
}

Authorizations

X-API-Keystringheaderrequired

Your API key. Create one in Ocoya. Authorization: Bearer <key> works too.

Query Parameters

brandIdstringrequired

Ocoya brand ID. Get one from GET /brands.

Example:"cmayvq3hk00017apshay5qezu"

Body

application/json
promptstringrequired

Prompt describing the post Ocoya should generate. Minimum 10 characters.

Minimum string length: 10
Example:"Write a launch post for our new analytics dashboard."
toneenum<string>

Caption tone for the AI draft. Defaults to professional.

Available options: professional, friendly, educational, bold, founder_led
Example:"professional"
postLengthenum<string>

Target caption length for the AI draft. Defaults to medium.

Available options: short, medium, long, extra_long
Example:"medium"
channelIdsstring[]

Channel IDs that should receive the post. Get IDs from GET /channels.

Example:
[
  "clh49poxf008x8kov4ncbjty9"
]
generateImageboolean

Whether to generate square image media for the AI draft.

Example:true
imageCountinteger

Number of generated images when generateImage is true. Use 1 for a single image or 2-10 for a carousel.

Required range: 1 <= x <= 10
Example:3
referenceUrlsstring[]

Optional image URLs to use as visual references when generateImage is true. Ocoya uses these images for style, composition, layout, and subject guidance; they are not attached directly to the post.

Example:
[
  "https://example.com/reference.png"
]
referenceDesignIdsstring[]

Optional Studio design IDs to use as visual references when generateImage is true. Get IDs from GET /studio-templates.

Example:
[
  "design_123"
]
studioDesignIdstring

Optional ID of the brand's own Studio design, from GET /studio-designs. The post's image is then that design, with its text layers written by the AI from the caption, instead of an AI-generated image. Every other layer stays as designed unless set in studioDesignFields. generateImage, imageCount and references are ignored.

Example:"design_123"
studioDesignFieldsobject

Optional values for the Studio design's layers, keyed by field ID from GET /studio-designs/{designId}: an image URL for an image field (a logo, a product photo), a CSS colour for a colour field, or text for a text field, which is then used as given instead of being written by the AI. Only used with studioDesignId.

Example:
{
  "pixy-cmte3datf00f435708hleujti": "https://example.com/logo.png"
}

Response

application/json

Queued. Returns immediately with status GENERATING; fetch the post later to see the completed draft.

postGroupIdstring

ID of the post. Fetch it later with GET /post to see the finished draft.

Example:"cmajvvb9q0003ja5vh0538j6r"
statusstring

GENERATING until the caption and media are ready.

Example:"GENERATING"
scheduledAtstring | null

When the post is scheduled, or null for a draft.