# 오토케 API

> 게시물 초안을 만들고 확인한 뒤, 연결된 소셜 미디어 채널에 바로 올리거나 원하는 시각에 예약할 수 있습니다.

## 5분 안에 시작하기

### 1. API 키 발급

1. [오토케 계정 페이지](https://autoke.ai/ko/account)에 로그인하십시오.
2. **API 키** 영역에서 **키 만들기**를 선택하십시오.
3. `ak_live_`로 시작하는 키를 복사해 안전한 곳에 보관하십시오.

전체 키는 발급 직후 한 번만 표시됩니다. API 키는 비밀번호처럼 다루고 브라우저 코드나 공개 저장소에 넣지 마십시오. API 키를 사용하려면 활성 구독이 필요합니다.

게시 요청에서 `subuserID`를 생략하면 API 키에 연결된 브랜드를 사용하며, 브랜드가 없는 키는 기본 계정의 채널을 사용합니다. 브랜드 정보를 반영해 글을 생성하려면 `subuserID`를 명시하십시오. 생성 요청은 키의 브랜드를 자동으로 적용하지 않습니다. 본인 계정에 등록된 ID를 사용하십시오.

> **권장**
>
> API를 자동화해 연속 호출한다면 크레딧 부족으로 작업이 중단되지 않도록 [결제 및 크레딧](https://autoke.ai/ko/billing)에서 자동 충전을 켜는 것을 권장합니다. 자동 충전은 지원되는 계정에서 사용할 수 있습니다.

### 2. 첫 게시물 초안 생성

모든 요청에 API 키와 JSON 형식을 알리는 헤더를 추가하십시오.

```bash
curl https://autoke.ai/api/v3/generate-post \
  -H "Authorization: Bearer ak_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
	"instruction": "여름 한정 복숭아 에이드 출시 소식 써줘",
    "platforms": ["threads"],
    "language": "Korean"
  }'
```

성공하면 자동으로 게시되지 않은 초안이 반환됩니다. 내용을 확인하고 필요한 경우 수정하십시오.

```json
{
	"success": true,
	"data": {
		"content": "올해 복숭아 당도가 유난히 좋아서 드디어 에이드 시작했어.\n\n매일 아침마다 잘 익은 것만 골라서 직접 청 담그는 게 일이지만 그래도 이 맛은 포기 못 해.\n\n인공 시럽 하나도 안 쓰고 오직 과육으로만 맛을 냈어.",
		"timeSlot": "Lunch Break"
	}
}
```

응답 예시이며 생성 문구는 매번 달라집니다. `timeSlot`은 추천 시간대이며 예약 시각이 아닙니다. 초안을 자동으로 예약하거나 게시하지 않습니다.

### 3. 확인한 게시물 게시

- 지금 게시: `POST /api/v3/post-now`
- 원하는 시각에 예약: `POST /api/v3/schedule-post`

> **중요**
>
> 게시 요청 전에 오토케 계정에 대상 플랫폼 채널이 연결되어 있어야 합니다.

Instagram에는 이미지나 비디오가 필요합니다.

## 사용 가능한 기능

### 게시물 초안 만들기

`POST /api/v3/generate-post`

원하는 주제와 말투를 `instruction`에 자연어로 입력하십시오. 결과는 `data.content`로 반환되며 게시물 생성 크레딧 20개를 사용합니다.

### 게시물 이미지 만들기

`POST /api/v3/generate-image`

원하는 장면을 `prompt`에 설명하십시오. 기존 이미지를 수정하려면 `imageURLs`와 `mode: "edit"`를 함께 보낼 수 있습니다. 이미지 생성 크레딧 300개를 사용합니다.

### 프로필 소개 문구 만들기

`POST /api/v3/generate-bio`

원하는 방향을 `instruction`에 입력하거나 기존 문구를 `content`로 보내십시오. 브랜드명, 브랜드 설명, 플랫폼을 함께 보내면 더 알맞은 결과를 만들 수 있습니다. 크레딧 20개를 사용합니다.

### 바로 게시하거나 예약하기

`POST /api/v3/post-now` 또는 `POST /api/v3/schedule-post`

지원 플랫폼은 `x`, `facebook`, `instagram`, `threads`, `youtube`, `tiktok`입니다. 응답의 `results`에서 플랫폼별 성공 여부를 확인할 수 있습니다.

## 요청 상세

운영 API 기본 주소는 `https://autoke.ai`이며, 문서 주소는 `https://docs.autoke.ai`입니다. 외부 연동에서는 운영 API 주소를 사용하십시오.

| 작업                          | 입력                                                                                                                               | 결과                            |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `POST /api/v3/generate-post`  | `instruction`, 기존 `content`, `referenceImageURL` 중 하나로 시작. 선택 항목: `platforms`, `language`, `subuserID`, `promotableID` | `data.content`, `data.timeSlot` |
| `POST /api/v3/generate-image` | `prompt`. 선택 항목: 공개 `imageURLs`, `mode: "edit"`                                                                              | `data.uploadedURL`              |
| `POST /api/v3/generate-bio`   | `instruction` 또는 `content`. 선택 항목: `platform`, `language`, `brandName`, `brandDescription`                                   | `data.content`                  |
| `POST /api/v3/post-now`       | 비어 있지 않은 `platforms`와 `content` 또는 `videoURL`. 아래의 미디어·플랫폼 옵션 추가 가능                                        | `success`, `results`, `postIDs` |
| `POST /api/v3/schedule-post`  | 게시 입력에 시간대가 포함된 미래 `scheduledAt` 추가                                                                                | `success`, `results`, `postIDs` |

생성 요청의 `language`에는 다음 값을 정확히 입력하십시오: `English`, `Korean`, `Japanese`, `Chinese`, `Spanish`, `French`, `German`, `Portuguese`, `Italian`, `Dutch`, `Russian`, `Arabic`, `Hindi`, `Indonesian`, `Vietnamese`. `en`, `ko` 같은 언어 코드는 사용할 수 없습니다. 게시물 생성에서는 브랜드의 언어 설정이 우선할 수 있습니다.

이미지 생성 결과의 `data.uploadedURL`을 게시 요청의 `imageURLs`에 넣으십시오. 대체 입력인 `images: [{ "url": "https://example.com/photo.jpg", "alt": "복숭아 에이드" }]`도 지원하며, 함께 보내면 `images`가 우선합니다. `topic`은 Threads 주제 태그입니다. `promotableID`는 기존 상품·서비스와 게시물 기록을 연결하며 본문을 자동으로 바꾸지 않습니다.

### 예약 예시

날짜는 실제 게시하려는 미래 시각으로 바꾸십시오.

```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": "제철 과일 음료가 준비되었습니다.",
    "platforms": ["threads"],
    "scheduledAt": "2030-08-01T09:00:00+09:00"
  }'
```

### 파일 직접 업로드

즉시 게시와 예약 모두 `multipart/form-data`도 받습니다. `platforms`는 쉼표로 구분한 문자열, 이미지 파일은 반복된 `image`, 동영상 파일은 `video`로 보내십시오. `youtube`, `tiktok` 옵션은 JSON 문자열로 전달하며, 예약 시 `scheduledAt`도 추가합니다. multipart Content-Type과 boundary는 HTTP 클라이언트가 설정하도록 두십시오.

```bash
curl https://autoke.ai/api/v3/post-now \
  -H "Authorization: Bearer ak_live_your_key" \
  -H "Accept: application/json" \
  -F 'content=제철 과일 음료가 준비되었습니다.' \
  -F 'platforms=instagram' \
  -F 'image=@photo.jpg'
```

## 플랫폼별 요구 사항

| 플랫폼      | 요구 사항                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| `x`         | 가중 글자 수 280자까지. 한·중·일 문자는 2자, URL은 23자로 계산                                         |
| `facebook`  | Facebook 채널 연결 필요                                                                                |
| `instagram` | 이미지 1개 이상 또는 동영상 필요                                                                       |
| `threads`   | 500자까지. `topic` 선택 가능                                                                           |
| `youtube`   | `videoURL`과 `youtube` 옵션 필요. `content`는 설명이며 UTF-8 기준 5000바이트까지                       |
| `tiktok`    | `videoURL`과 `tiktok` 옵션 필요. `tiktok.title`이 해시태그를 포함한 본문이며 `content`는 사용하지 않음 |

YouTube와 TikTok은 기존 동영상 업로드용이며 동영상을 생성하는 API가 아닙니다. YouTube 채널 연결은 계정별로 순차 개방 중이며, 개방 상태는 [현재 API 문서](https://docs.autoke.ai/ko)를 확인하십시오. YouTube는 요청한 `privacyStatus` 그대로 게시됩니다.

### YouTube 옵션

`youtube.title`(공백 외 내용 필수, 최대 100자, `<`와 `>` 금지), `privacyStatus`(`public`, `unlisted`, `private`), `madeForKids`(boolean), `containsSyntheticMedia`(boolean)는 필수입니다. `notifySubscribers`만 선택 항목이며 생략 시 false입니다.

### TikTok 옵션

`title`(공백 외 내용 필수, 최대 2200자), `privacyLevel`, 그리고 boolean 항목 `allowComment`, `allowDuet`, `allowStitch`, `brandOrganic`, `brandContent`, `isAIGC`를 모두 보내야 합니다.

`privacyLevel`은 `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY` 중 연결된 계정에서 허용하는 값이어야 합니다. `brandContent: true`와 `SELF_ONLY`는 함께 사용할 수 없습니다. 댓글·듀엣·스티치도 계정 설정에 따라 제한될 수 있습니다.

공개 범위와 고지 항목은 게시 전에 사용자가 선택한 실제 값을 보내십시오. 필수 옵션이 빠지거나 유효하지 않으면 HTTP 400으로 거절됩니다. 대화형 문서에 YouTube·TikTok의 즉시 게시 및 예약 요청 전체 예시가 있습니다.

## 게시 크레딧과 동영상 주소

게시·예약은 플랫폼별 게시물 기록 하나당 100크레딧을 사용합니다. 예약은 발행 시점이 아닌 예약 저장 시 차감합니다. 예를 들어 두 플랫폼에 예약하면 생성 비용과 별도로 200크레딧이 필요합니다. 크레딧이 부족해 기록 생성에 실패한 플랫폼은 HTTP 200의 `results[].error`에 표시될 수 있습니다.

동영상 URL의 경로는 `.mp4`, `.mov`, `.avi`, `.mkv`, `.webm` 중 하나로 끝나야 동영상으로 인식됩니다. 확장자가 없는 주소는 사용하지 마십시오. TikTok의 `videoURL`은 오토케에 업로드된 공개 media 버킷 주소여야 하며 임의의 외부 동영상 URL은 사용할 수 없습니다. 외부 파일은 위의 multipart `video` 필드로 업로드하십시오. YouTube 설명에도 `<`와 `>`는 넣을 수 없습니다.

## 오류 응답 확인하기

생성 요청이 실패하면 HTTP 상태 코드와 함께 `success: false`가 반환됩니다. `error.code`는 HTTP 상태 코드와 같고, `error.message`에서 구체적인 원인을 확인할 수 있습니다.

```json
{
	"success": false,
	"error": {
		"code": 401,
		"message": "유효하지 않은 API 키입니다"
	}
}
```

- `400 잘못된 요청`: 필수 값이 없거나 형식이 올바르지 않습니다. 해당 작업의 요청 예시와 필수 필드를 확인하십시오.
- `401 인증 실패`: API 키가 빠졌거나 유효하지 않습니다. `Authorization: Bearer YOUR_API_KEY` 형식인지 확인하십시오.
- `402 크레딧 부족`: 생성에 필요한 크레딧이 부족합니다. 잔여 크레딧을 확인하고, 연속 호출에는 자동 충전 사용을 권장합니다.
- `403 구독 필요`: 현재 구독으로 API 키를 사용할 수 없습니다. 구독 상태를 확인하십시오.
- `500 서버 오류`: 서버에서 요청을 처리하지 못했습니다. 잠시 후 다시 시도하십시오.

예를 들어 생성에 필요한 크레딧이 부족하면 다음과 같은 `402` 응답이 반환됩니다.

```json
{
	"success": false,
	"error": {
		"code": 402,
		"message": "크레딧이 부족합니다"
	}
}
```

HTTP 200이어도 일부 또는 모든 플랫폼에서 실패할 수 있습니다. 최상위 `success`는 하나 이상의 플랫폼이 성공하면 true이며, `data` 없이 `results`와 `postIDs`가 반환됩니다. `results`의 각 항목을 확인하십시오. `postIDs`는 소셜미디어 ID가 아닌 오토케 게시물 기록 ID이며, 기록 생성 후 게시에 실패한 ID도 포함될 수 있습니다. 예약 성공은 예약 저장을 의미하며 실제 발행은 나중에 수행됩니다.

게시 검증 오류는 생성 오류와 달리 HTTP 400에 `{ "message": "scheduledAt is required" }` 같은 본문으로 반환됩니다. 인증·예상하지 못한 게시 오류도 생성 오류 형식 대신 프레임워크 오류 응답을 사용할 수 있습니다. `Accept: application/json`을 보내고 HTTP 상태와 Content-Type을 확인한 뒤 `error.message` 또는 `message`를 읽으십시오.

일부 실패나 타임아웃 후 다시 게시하기 전에는 `results`와 오토케 캘린더를 확인하십시오. 전체 요청을 반복하면 중복 게시될 수 있습니다.

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

## 더 자세히 보기

- [대화형 API 문서](https://docs.autoke.ai/ko)
- [OpenAPI 3.1 명세](https://docs.autoke.ai/openapi/ko.json)
- [오토케 계정](https://autoke.ai/ko/account)

- [LLM 문서 인덱스](https://docs.autoke.ai/llms.txt)