# Autoke API

> Create a post draft, review it, and then publish immediately or schedule it for connected social media channels.

## Get started in five minutes

### 1. Create an API key

1. Sign in to your [Autoke account](https://autoke.ai/en/account).
2. Open **API keys** and select **Create key**.
3. Copy the key beginning with `ak_live_` and store it securely.

The full key is shown only once. Treat it like a password and never expose it in browser code or a public repository. An active subscription is required.

For publishing, omitting `subuserID` uses the brand associated with the API key, or the main account if the key has no brand. For brand-aware post generation, send `subuserID` explicitly; generation does not automatically inherit the key's brand. Use IDs from your own Autoke account.

> **Recommended**
>
> For automated or continuous API calls, enable [Auto Top-Up](https://autoke.ai/en/billing) to prevent jobs from stopping when credits run low. Auto Top-Up is available for supported accounts.

### 2. Create your first post draft

Send your API key and JSON content type with every request.

```bash
curl https://autoke.ai/api/v3/generate-post \
  -H "Authorization: Bearer ak_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
	"instruction": "Write a friendly post about our summer peach ade",
    "platforms": ["threads"],
    "language": "English"
  }'
```

A successful request returns a draft without publishing it. Review and edit the content before moving on.

```json
{
	"success": true,
	"data": {
		"content": "We spend more time peeling these peaches than actually making the drink. Using only ripe fruit means we have to hand-peel them to keep the texture right for the syrup. \n\nIf you use a machine or blanch them for too long, they lose that specific floral scent that makes the ade work. The sugar ratio has to stay at exactly 1:1 to balance the acidity of the lemon.\n\nIt is a lot of prep for one drink.",
		"timeSlot": "Lunch Break"
	}
}
```

This is an example response; generated text varies. `timeSlot` is a suggested time slot, not a scheduled timestamp. It does not schedule or publish the draft.

### 3. Publish the approved post

- Publish now: `POST /api/v3/post-now`
- Choose a future time: `POST /api/v3/schedule-post`

> **Important**
>
> Connect the target platform channels in Autoke before sending a publishing request.

Instagram requires an image or video.

## What can you build?

### Create a post draft

`POST /api/v3/generate-post`

Describe the topic and tone in natural language with `instruction`. The draft is returned in `data.content` and uses 20 credits.

### Create an image for a post

`POST /api/v3/generate-image`

Describe the scene in `prompt`. To edit an existing image, include `imageURLs` and `mode: "edit"`. Uses 300 credits.

### Create a profile bio

`POST /api/v3/generate-bio`

Describe the desired bio in `instruction` or provide an existing bio in `content`. Brand and platform details produce a more relevant result. Uses 20 credits.

### Publish now or schedule

`POST /api/v3/post-now` or `POST /api/v3/schedule-post`

Supported platforms are `x`, `facebook`, `instagram`, `threads`, `youtube`, and `tiktok`. Check `results` for the outcome on each platform. YouTube and TikTok upload an existing video; these endpoints do not generate videos.

## Request details

The production API base URL is `https://autoke.ai`. The documentation host is `https://docs.autoke.ai`; use the production base URL in your integration.

| Operation                     | Input                                                                                                                                     | Result                          |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `POST /api/v3/generate-post`  | Start with `instruction`, existing `content`, or `referenceImageURL`; optionally add `platforms`, `language`, `subuserID`, `promotableID` | `data.content`, `data.timeSlot` |
| `POST /api/v3/generate-image` | `prompt`; optional public `imageURLs` and `mode: "edit"`                                                                                  | `data.uploadedURL`              |
| `POST /api/v3/generate-bio`   | `instruction` or `content`; optional `platform`, `language`, `brandName`, `brandDescription`                                              | `data.content`                  |
| `POST /api/v3/post-now`       | Nonempty `platforms` plus `content` or `videoURL`; optional media and platform options below                                              | `success`, `results`, `postIDs` |
| `POST /api/v3/schedule-post`  | Publishing fields plus a future `scheduledAt` with a time-zone offset                                                                     | `success`, `results`, `postIDs` |

Generation `language` accepts these exact values: `English`, `Korean`, `Japanese`, `Chinese`, `Spanish`, `French`, `German`, `Portuguese`, `Italian`, `Dutch`, `Russian`, `Arabic`, `Hindi`, `Indonesian`, `Vietnamese`. Do not send locale codes such as `en` or `ko`. Brand language can override the post generation language.

Use the generated `data.uploadedURL` in publishing `imageURLs`. Alternatively send `images: [{ "url": "https://example.com/photo.jpg", "alt": "A peach ade" }]`; `images` takes precedence over `imageURLs`. `topic` adds a Threads topic tag. `promotableID` associates the post record with an existing product or service without rewriting the content.

### Schedule example

Replace the date with your intended future publishing time.

```bash
curl https://autoke.ai/api/v3/schedule-post \
  -H "Authorization: Bearer ak_live_your_key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "content": "Our seasonal drinks are ready.",
    "platforms": ["threads"],
    "scheduledAt": "2030-08-01T09:00:00+09:00"
  }'
```

### Upload files directly

Both publishing endpoints also accept `multipart/form-data`. Send `platforms` as a comma-separated string, repeat `image` for image files, and use `video` for a video file. Send `youtube` and `tiktok` as JSON strings. Include `scheduledAt` when scheduling. Let your HTTP client set the multipart content type and boundary.

```bash
curl https://autoke.ai/api/v3/post-now \
  -H "Authorization: Bearer ak_live_your_key" \
  -H "Accept: application/json" \
  -F 'content=Our seasonal drinks are ready.' \
  -F 'platforms=instagram' \
  -F 'image=@photo.jpg'
```

## Platform requirements

| Platform    | Requirements                                                                                             |
| ----------- | -------------------------------------------------------------------------------------------------------- |
| `x`         | Up to 280 weighted characters; CJK characters count as 2 and URLs as 23                                  |
| `facebook`  | A connected Facebook channel                                                                             |
| `instagram` | At least one image or a video                                                                            |
| `threads`   | Up to 500 characters; optional `topic`                                                                   |
| `youtube`   | `videoURL` and `youtube` options; `content` is the description, up to 5000 UTF-8 bytes                   |
| `tiktok`    | `videoURL` and `tiktok` options; `tiktok.title` is the caption including hashtags; `content` is not used |

YouTube channel connections are being opened account by account. Check the [current reference](https://docs.autoke.ai/en) for availability. YouTube posts use the requested `privacyStatus`.

### YouTube options

Send `youtube.title` (nonempty, up to 100 characters, no `<` or `>`), `privacyStatus` (`public`, `unlisted`, `private`), `madeForKids` (boolean), and `containsSyntheticMedia` (boolean). These fields are required. `notifySubscribers` is optional and defaults to false.

### TikTok options

All fields are required: `title` (nonempty, up to 2200 characters), `privacyLevel`, and booleans `allowComment`, `allowDuet`, `allowStitch`, `brandOrganic`, `brandContent`, `isAIGC`.

`privacyLevel` must be one of `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY`, and must also be allowed by the connected account. `brandContent: true` cannot be combined with `SELF_ONLY`. Account settings can also disable comments, Duet, or Stitch.

Get the user's actual choices for visibility and disclosures before submitting video options. Missing or invalid required options cause HTTP 400. The interactive reference includes complete YouTube and TikTok request examples for immediate and scheduled publishing.

## Publishing credits and video URLs

Publishing or scheduling costs 100 credits per platform/post record, separate from generation. Scheduling charges when the reservation is saved, not when it is delivered. For example, scheduling to two platforms requires 200 publishing credits. Insufficient credit during record creation can appear in `results[].error` with HTTP 200.

The video URL pathname must end in `.mp4`, `.mov`, `.avi`, `.mkv`, or `.webm` to be recognized as a video. Avoid extensionless URLs. TikTok `videoURL` must be an Autoke-uploaded public media bucket URL; arbitrary external video URLs are not supported. Upload external files using the multipart `video` field above. YouTube descriptions must also exclude `<` and `>`.

## Handle errors

A failed generation request returns `success: false` with an HTTP status code. `error.code` matches that status, while `error.message` explains the specific cause.

```json
{
	"success": false,
	"error": {
		"code": 401,
		"message": "Invalid API key"
	}
}
```

- `400 Bad Request`: A required value is missing or invalid. Review the operation's required fields and request example.
- `401 Unauthorized`: The API key is missing or invalid. Check for the `Authorization: Bearer YOUR_API_KEY` format.
- `402 Insufficient Credit`: The account does not have enough credits for generation. Check the balance, and enable Auto Top-Up for continuous API calls.
- `403 Subscription Required`: The current subscription cannot use API keys. Check the subscription status.
- `500 Server Error`: The server could not process the request. Try again later.

Publishing requests can return HTTP 200 while failing on one or all platforms. The top-level `success` is true when at least one platform succeeds. Check every item in `results`; there is no `data` wrapper. `postIDs` contains Autoke record IDs, including records whose subsequent publishing failed, not social network IDs. Scheduling success means the reservation was saved; delivery happens later.

Publishing validation errors use a different body, for example HTTP 400 with `{ "message": "scheduledAt is required" }`. Authentication and unexpected publishing errors may also use the framework error response instead of the generation envelope. Send `Accept: application/json`, check the HTTP status and content type, and read `error.message` or `message` as available.

Before retrying a publishing request after partial failure or timeout, inspect `results` and the Autoke calendar. Repeating the whole request can create duplicate posts.

```json
{
	"success": false,
	"results": [
		{
			"platform": "instagram",
			"success": false,
			"error": "No instagram channel found"
		}
	],
	"postIDs": []
}
```

## Learn more

- [Interactive API documentation](https://docs.autoke.ai/en)
- [OpenAPI 3.1 document](https://docs.autoke.ai/openapi/en.json)
- [Autoke account](https://autoke.ai/en/account)

- [LLM documentation index](https://docs.autoke.ai/llms.txt)