AiVideoEditor
무료로 시작하기
메뉴

검토 2026-11-11 · API 버전 2026-11-09 · Markdown 읽기

AiVideoEditor API 퀵스타트

Base URL: https://<your-app-host>/api/v1 (로컬 개발: http://localhost:3006/api/v1).

인증

워크스페이스 탐색의 Developers(/app/developers)에서 product key를 만드세요. 평문 키(pk_v1_…)는 딱 한 번만 표시돼요; 해시와 짧은 접두사만 저장돼요. bearer 토큰으로 보내세요:

curl -H "Authorization: Bearer $PUBLISHER_KEY" https://app.example.com/api/v1/usage

키에는 명시적 스코프(accounts:read, media:write, posts:read, posts:write, posts:publish, usage:read, webhooks:manage)와 선택적 계정 허용 목록이 있어요. draft-only 키는 posts:publish가 빠져 있어서 게시, 예약, 취소, 재시도를 할 수 없어요. 키는 다른 키를 만들거나 결제를 변경할 수 없어요. 키를 폐기하면 미전송 작업이 requires_action 상태로 일시 중지돼요: 아무것도 삭제되지 않고, 폐기 UI는 영향받는 대기 작업 수를 먼저 보여줘요.

기본 규칙

  • 모든 변경 작업에는 Idempotency-Key 헤더가 필요해요. 같은 키 + 같은 본문 → 같은 기록된 결과(같은 전송 ID). 같은 키 + 다른 본문 → 409 idempotency_conflict.
  • 편집과 예약에는 expectedVersion이 필요하고, 오래된 버전이면 현재 버전이 담긴 error.details.currentVersion과 함께 409 revision_conflict를 반환해요.
  • publish/schedule의 202는 전송 접수를 의미할 뿐, "게시됨"이 절대 아니에요. GET /posts/{id}, 고객 웹훅, 또는 제한된 폴링으로 결과를 추적하세요.
  • 속도 제한은 워크스페이스별 기술적 속도 제한이에요(플랜별 60/120/240 req/min; 429 + Retry-After). 요청이나 게시 할당량은 없어요: 모든 유료 플랜에서 게시는 무제한이에요.
  • 오류는 정규화된 봉투를 사용해요: { error: { code, message, fieldErrors?, destinationErrors?, retryable?, retryAfterSeconds?, requestId } }.

엔드투엔드: 초안 → 검증 → 게시 → 관찰

이 예제에는 Bash, curl, jq, Node 22+, 활성 워크스페이스, 연결된 Facebook Page 또는 LinkedIn 수신처, 그리고 accounts:read, posts:read, posts:write, posts:publish 권한이 있는 키가 필요해요. ACCOUNT_ID를 /accounts의 허용된 수신처로 설정하고, /capabilities에서 텍스트 형식 지원 여부를 확인하세요. publish 명령을 실행하면 실제 콘텐츠가 게시돼요.

set -euo pipefail
BASE="${PUBLISHER_API_URL:?Set the AiVideoEditor origin}/api/v1"
AUTH="Authorization: Bearer ${PUBLISHER_KEY:?Set the product key}"
JSON="Content-Type: application/json"
new_key() { node -e 'console.log(require("node:crypto").randomUUID())'; }

curl --fail-with-body -sS -H "$AUTH" "$BASE/accounts"
curl --fail-with-body -sS -H "$AUTH" "$BASE/capabilities"
: "${ACCOUNT_ID:?Choose a permitted text destination from the responses above}"

# Save this key and body; reuse both if the connection fails ambiguously.
CREATE_KEY=$(new_key)
DRAFT_BODY=$(jq -n --arg account "$ACCOUNT_ID" '{caption:"A new update from our team.",mediaIds:[],brandFolderId:null,destinations:[{accountId:$account,format:"text"}]}')
DRAFT=$(curl --fail-with-body -sS -X POST -H "$AUTH" \
  -H "Idempotency-Key: $CREATE_KEY" -H "$JSON" \
  "$BASE/posts" -d "$DRAFT_BODY")
POST_ID=$(jq -er '.post.postId' <<<"$DRAFT")
VERSION=$(jq -er '.post.version' <<<"$DRAFT")

VALIDATION=$(curl --fail-with-body -sS -X POST -H "$AUTH" "$BASE/posts/$POST_ID/validate")
printf '%s\n' "$VALIDATION"
jq -e '.validation.valid == true' <<<"$VALIDATION" >/dev/null

# 202 means accepted. Keep this key for an identical retry after a timeout.
PUBLISH_KEY=$(new_key)
ACCEPTED=$(curl --fail-with-body -sS -X POST -H "$AUTH" \
  -H "Idempotency-Key: $PUBLISH_KEY" "$BASE/posts/$POST_ID/publish")
printf '%s\n' "$ACCEPTED"
curl --fail-with-body -sS -H "$AUTH" "$BASE/posts/$POST_ID"

이미지/영상 수신처의 경우 먼저 미디어를 업로드하고 확정한 다음, 반환된 asset ID를 mediaIds에 넣고 적격한 수신처 형식을 사용하세요. 접수 응답에서 개별 전송 ID를 확인하고, 웹훅이나 백오프가 있는 제한된 상태 폴링을 사용하세요. 즉시 상태를 한 번 조회하는 것만으로는 여전히 pending일 수 있어요.

게시 대신 예약

위의 게시 단계 대신 초안에 이걸 사용하세요. 편집 후에는 현재 버전을 다시 조회하세요. 만료될 샘플 날짜를 쓰는 대신 미래 시각을 계산해요.

SCHEDULED_AT=$(node -e 'console.log(new Date(Date.now()+86400000).toISOString())')
SCHEDULE_BODY=$(jq -n --arg at "$SCHEDULED_AT" --argjson version "$VERSION" \
  '{scheduledAt:$at,timezone:"America/Indiana/Indianapolis",expectedVersion:$version}')
SCHEDULE_KEY=$(new_key)
curl --fail-with-body -sS -X POST -H "$AUTH" -H "Idempotency-Key: $SCHEDULE_KEY" \
  -H "$JSON" "$BASE/posts/$POST_ID/schedule" -d "$SCHEDULE_BODY"

시각은 미래여야 하고 90일 범위 안에 있어야 해요; UTC 시각과 표시용 타임존은 별도로 저장돼요. API 키가 그 시각 이전이나 그 시각에 만료되면 접수 응답에 코드 key_expires_before_schedule이 담긴 warnings 항목이 포함돼요. 전송은 예약 상태로 유지되지만, 게시되려면 활성 주체로 검토 후 다시 제출돼야 해요. 요청을 재생할 때도 같은 경고가 유지돼요. 아직 안전하게 접수되지 않은 상태일 때 취소하세요:

curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/cancel
# Already submitted? → 409 too_late_to_cancel with the real state.

재시도는 알려진 실패한 수신처에만 하세요(알 수 없음/성공은 거부돼요):

curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" $BASE/deliveries/$DELIVERY_ID/retry

미디어(직접 업로드)

미디어 바이트는 이 API를 통과하지 않아요.

# 1. Reserve bytes → direct instructions (presigned PUT, or multipart for large files)
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/upload-intents -d '{
  "filename": "poster.jpg", "declaredMime": "image/jpeg", "declaredBytes": 1048576 }'

# 2. Upload bytes DIRECTLY to the returned URL with the documented method.

# 3. Finalize: the server verifies size/signature on the immutable final copy.
#    Send ONLY the session identity (plus part receipts for multipart uploads)
#: bytes, MIME and checksum are observed server-side, never declared here.
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/$ASSET_ID/finalize -d '{
  "sessionId": "…" }'

# multipart: include the ETag receipt of every uploaded part.
# Files at or above 50 MiB use multipart; use the returned part size and URLs.
# Upload every part and retain its ETag. Small files finalize with sessionId only.
# These are alternative finalization shapes, not two consecutive operations.
curl -s -X POST -H "$AUTH" -H "Idempotency-Key: $(new_key)" -H "$JSON" $BASE/media/$ASSET_ID/finalize -d '{
  "sessionId": "…",
  "multipart": { "parts": [ { "partNumber": 1, "etag": "…" } ] } }'

# 4. Status/expiry only: there is no permanent public media URL
curl -s -H "$AUTH" $BASE/media/$ASSET_ID

파일은 임시적이에요: 예약된 게시물은 게시까지 미디어를 유지하고, 동적 deleteAfter(또는 null)가 항상 표시돼요. 원본은 직접 보관하세요.

사용량

GET /usage는 플랜, 연결/예약된 계정 슬롯, 멤버, 스토리지, 90일 범위, 속도 정보를 보고해요. 활동 숫자는 운영 지표일 뿐이에요: 제품 어디에도 남은 게시 카운터는 없어요.

페이지네이션

목록 엔드포인트는 불투명 커서를 사용해요: ?limit=25&cursor=<nextCursor>. 타임스탬프는 UTC ISO-8601이에요. nextCursor가 null이 될 때까지 계속하세요; 필터링된 게시물 페이지가 비어 있어도 non-null 커서가 아직 스캔할 오래된 레코드를 가리킬 수 있어요. 촘촘한 상태 루프보다는 웹훅(webhooks 참고)이나 백오프가 있는 제한된 폴링을 권장해요.

제한과 부분 성공

수신처 capabilities(GET /capabilities에서 가져옴)에는 앱, 제공자, 네트워크, 계정 중 가장 엄격한 실효 제한이 담겨요. 제한이 요청을 막으면 오류 봉투는 실행 가능한 정보를 줘요:

{
  "error": {
    "code": "storage_limit",
    "message": "Active temporary media exceeds this plan's storage allowance.",
    "retryable": false,
    "requestId": "…"
  }
}

account_limit, seat_limit, storage_limit, subscription_inactive, trial_expired는 402 응답이에요; 아무것도 삭제되지 않고 초안/대기 작업은 업그레이드 후를 위해 보존돼요.

게시/예약은 독립적인 수신처 작업의 묶음이에요. 부분 성공은 정상이며 수신처별로 보고돼요: 원자적 약속으로는 절대 보고되지 않아요:

{
  "post": {
    "postId": "…",
    "version": 4,
    "status": "partially_published",
    "deliveries": [
      { "id": "…", "accountId": "…", "network": "instagram", "state": "published",
        "nativePostUrl": "https://instagram.com/p/…", "unresolvedExternalOutcome": false },
      { "id": "…", "accountId": "…", "network": "linkedin", "state": "reconnect_required",
        "nativePostUrl": null, "lastErrorCode": "reconnect_required" }
    ]
  },
  "requestId": "…"
}

실패한 수신처만 재시도하고(POST /deliveries/{id}/retry) 성공한 수신처는 다시 보내지 않아요. 동의/재연결 요구는 안전한 안내와 함께 requires_action을 반환하며, 절대 시크릿을 반환하지 않아요.

전체 참조

TikTok의 경우 GET /accounts/{id}/tiktok/settings가 연결된 크리에이터의 현재 공개 범위 선택, 상호작용 권한, 길이 제한, 게시 모드 가용성을 반환해요. accounts:read가 필요하고 키 허용 목록을 따라요. 초안 저장이나 이 설정 조회만으로는 동의가 공급되지 않아요.

현재 사람 확인이 없는 게시/예약은 HTTP 409 consent_required를 반환하며, error.requiresAction.url은 인증된 컴포저에 저장된 초안을 가리켜요. 검증도 구조화된 문제와 함께 같은 핸드오프를 반환할 수 있어요. 사람이 정확한 영상/게시물 문구를 검토하고 그곳에서 명시적으로 선택해요; product key와 MCP는 대신 확인할 수 없어요. 사람이 확인한 후에는 일반 공유 게시 서비스를 통해 재시도하세요. 콘텐츠를 편집하거나 수신처 신원을 바꾸면 새로운 검토가 필요해요. 핸드오프 URL에는 product key, 토큰, 서명된 미디어 URL이 없고, 워크스페이스 멤버십이 없는 사람에게 접근을 허용하지 않아요. 그 워크스페이스 UUID는 키의 워크스페이스를 식별해요; 다른 워크스페이스를 선택한 브라우저는 이 초안을 검토하기 전에 현재 멤버십 확인 후 명시적으로 전환해야 해요.

완전하고 최신인 계약은 OpenAPI specification을 참고하세요. UI, REST, MCP가 모두 같은 서비스를 읽기 때문에 같은 워크스페이스 규칙을 적용해요. 결과는 각 요청의 현재 상태를 반영해요; 별개의 요청은 그 사이의 업데이트를 관찰할 수 있어요.