REST API

API Documentation

Tích hợp đầy đủ tính năng tạo video AI, hình ảnh, TTS vào ứng dụng của bạn. API RESTful với JSON — không thư viện đặc biệt, không setup phức tạp.

Base URL

api.autovideo.app/api

Auth

Bearer Token

Format

JSON

Version

v1 stable

Bắt đầu

Base URL

https://api.autovideo.app/api

Xác thực

Tất cả endpoint (trừ login/register) yêu cầu Bearer token trong header HTTP. Lấy token bằng cách gọi POST /auth/login.

Authorization Header
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

Định dạng Response

Mọi response đều là JSON. Danh sách dữ liệu được bọc trong key data. Lỗi trả về theo format chuẩn:

Lỗi (4xx / 5xx)
{
  "message": "Thông tin đăng nhập không đúng",
  "errors": {
    "email": ["Email is required."]
  }
}

HTTP Status Codes

200 OKThành công
201 CreatedTạo mới thành công
400 Bad RequestTham số không hợp lệ
401 UnauthorizedThiếu hoặc sai Bearer token
404 Not FoundResource không tồn tại
422 UnprocessableValidation thất bại
500 Server ErrorLỗi server

Lưu ý: Async Generation

Các API tạo video / ảnh / TTS trả về ngay lập tức với status: "pending". Dùng POST /task/check để polling trạng thái item cho đến khi status: "completed" hoặc "failed".

Xác thực

5 endpoints
POST/auth/login

Đăng nhập và nhận Bearer token

Tham số

Tham sốKiểuBắt buộcMô tả
emailstringĐịa chỉ email của tài khoản
passwordstringMật khẩu

Request Body (JSON)

{
  "email": "user@example.com",
  "password": "secret123"
}

Response (200 OK)

{
  "access_token": "eyJ0eXAiOiJKV1QiLC...",
  "token_type": "Bearer",
  "user": {
    "id": 1,
    "fullname": "Nguyễn Văn A",
    "email": "user@example.com"
  }
}
POST/auth/register

Đăng ký tài khoản mới

Tham số

Tham sốKiểuBắt buộcMô tả
fullnamestringHọ và tên
emailstringEmail (unique)
passwordstringMật khẩu (tối thiểu 6 ký tự)
password_confirmationstringXác nhận mật khẩu
phone_numberstringSố điện thoại

Request Body (JSON)

{
  "fullname": "Nguyễn Văn A",
  "email": "user@example.com",
  "password": "secret123",
  "password_confirmation": "secret123"
}

Response (200 OK)

{
  "access_token": "eyJ0eXAiOiJKV1QiLC...",
  "token_type": "Bearer",
  "user": { "id": 2, "fullname": "Nguyễn Văn A", "email": "user@example.com" }
}
POST/auth/google

Đăng nhập bằng Google OAuth

Tham số

Tham sốKiểuBắt buộcMô tả
id_tokenstringGoogle ID Token từ Google OAuth 2.0

Request Body (JSON)

{ "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6..." }

Response (200 OK)

{ "access_token": "eyJ0...", "token_type": "Bearer", "user": { ... } }
GET/auth/profile
Bearer Token

Lấy thông tin tài khoản hiện tại

Response (200 OK)

{
  "id": 1,
  "fullname": "Nguyễn Văn A",
  "email": "user@example.com",
  "created_at": "2025-01-01T00:00:00Z"
}
POST/auth/logout
Bearer Token

Đăng xuất và thu hồi token hiện tại

Response (200 OK)

{ "message": "Logged out successfully" }

Task

4 endpoints
GET/task/items
Bearer Token

Danh sách tất cả item của user (phân trang)

Tham số

Tham sốKiểuBắt buộcMô tả
pageintegerTrang hiện tại
GET/task/items/{itemId}
Bearer Token

Chi tiết một item theo ID

Tham số

Tham sốKiểuBắt buộcMô tả
itemIdintegerID của item (path parameter)

Response (200 OK)

{
  "item_id": 1,
  "task_id": 100,
  "status": "completed",
  "prompt_text": "A sunset over the ocean",
  "model": "VEO_2_0_GENERATE_001",
  "aspect_ratio": "ASPECT_RATIO_16_9",
  "output_url": "https://cdn.autovideo.app/...",
  "thumbnail_url": "https://cdn.autovideo.app/..."
}
POST/task/check
Bearer Token

Kiểm tra trạng thái nhiều item cùng lúc (polling)

Tham số

Tham sốKiểuBắt buộcMô tả
item_idsinteger[]Mảng các item_id cần kiểm tra

Request Body (JSON)

{ "item_ids": [1, 2, 3] }

Response (200 OK)

{
  "data": [
    { "item_id": 1, "status": "completed", "output_url": "https://..." },
    { "item_id": 2, "status": "processing" },
    { "item_id": 3, "status": "failed" }
  ]
}
POST/task/delete
Bearer Token

Xóa task hoặc item (phải truyền một trong hai)

Tham số

Tham sốKiểuBắt buộcMô tả
task_idsinteger[]Mảng task_id cần xóa (xóa toàn bộ task + items)
item_idsinteger[]Mảng item_id cần xóa (task bị xóa nếu không còn item)

Request Body (JSON)

{ "task_ids": [100, 101] }

Response (200 OK)

{ "message": "Tasks deleted successfully" }

Video AI

5 endpoints
POST/ai/google/video/generate
Bearer Token

Tạo video AI từ văn bản hoặc ảnh (batch)

Tham số

Tham sốKiểuBắt buộcMô tả
accountIdintegerID tài khoản Google AI dùng để tạo
generationModestring`TEXT_TO_VIDEO` | `IMAGE_TO_VIDEO`
recaptchaTokenstringToken reCAPTCHA (tự động xử lý bởi SDK)
parentIdintegerItem ID cha nếu thêm vào task đang có
requestsarrayMảng yêu cầu tạo video (tối đa 50)
requests[].promptstringMô tả nội dung video
requests[].modelstringModel key: `VEO_3`, `VEO_2`, `VEO_2_0_GENERATE_001`…
requests[].aspectRatiostring`ASPECT_RATIO_16_9` | `ASPECT_RATIO_9_16` | `ASPECT_RATIO_1_1`
requests[].attachmentIdsinteger[]Attachment ID (cho image-to-video)

Request Body (JSON)

{
  "accountId": 5,
  "generationMode": "TEXT_TO_VIDEO",
  "recaptchaToken": "03AFcWeA...",
  "requests": [
    {
      "prompt": "A cinematic shot of waves crashing on shore at golden hour",
      "model": "VEO_3",
      "aspectRatio": "ASPECT_RATIO_16_9"
    },
    {
      "prompt": "Cherry blossoms falling in slow motion",
      "model": "VEO_3",
      "aspectRatio": "ASPECT_RATIO_9_16"
    }
  ]
}

Response (200 OK)

{
  "data": [
    {
      "item_id": 10,
      "task_id": 100,
      "status": "pending",
      "prompt_text": "A cinematic shot of waves...",
      "model": "VEO_3_GENERATE_001",
      "aspect_ratio": "ASPECT_RATIO_16_9"
    }
  ]
}
POST/ai/google/video/extend
Bearer Token

Kéo dài video hiện có theo frame

Tham số

Tham sốKiểuBắt buộcMô tả
accountIdintegerID tài khoản Google AI
itemIdintegerItem ID của video nguồn (phải thuộc user)
promptstringMô tả đoạn tiếp theo
startFrameIndexintegerFrame bắt đầu kéo dài (≥ 0)
endFrameIndexintegerFrame kết thúc (≥ startFrameIndex)
videoModelKeystringModel key sử dụng
aspectRatiostringTỉ lệ khung hình
seedintegerSeed tạo ngẫu nhiên

Request Body (JSON)

{
  "accountId": 5,
  "itemId": 10,
  "prompt": "The camera slowly pans right revealing mountains",
  "startFrameIndex": 0,
  "endFrameIndex": 24,
  "videoModelKey": "VEO_3",
  "aspectRatio": "ASPECT_RATIO_16_9"
}

Response (200 OK)

{ "item_id": 11, "status": "pending", "generation_mode": "EXTEND_VIDEO" }
POST/ai/google/video/concatenation
Bearer Token

Ghép nhiều video thành một (batch concat)

Tham số

Tham sốKiểuBắt buộcMô tả
inputVideosarrayMảng ≥ 2 video cần ghép
inputVideos[].itemIdintegerItem ID video (phải completed)
inputVideos[].lengthNanosintegerĐộ dài clip (nanoseconds)
inputVideos[].startTimeOffsetstringThời gian bắt đầu, e.g. `0s`
inputVideos[].endTimeOffsetstringThời gian kết thúc, e.g. `8s`

Request Body (JSON)

{
  "inputVideos": [
    { "itemId": 10, "lengthNanos": 8000000000, "startTimeOffset": "0s", "endTimeOffset": "8s" },
    { "itemId": 11, "lengthNanos": 6000000000, "startTimeOffset": "0s", "endTimeOffset": "6s" }
  ]
}

Response (200 OK)

{ "item_id": 15, "status": "pending", "generation_mode": "CONCATENATION" }
POST/ai/google/video/download
Bearer Token

Kích hoạt tải xuống / upscale video

Tham số

Tham sốKiểuBắt buộcMô tả
item_idintegerItem ID video
resolutionstring`VIDEO_RESOLUTION_ORIGINAL` | `VIDEO_RESOLUTION_1080P` | `VIDEO_RESOLUTION_4K`
modelstringModel key của video
aspect_ratiostringTỉ lệ khung hình của video

Request Body (JSON)

{
  "item_id": 10,
  "resolution": "VIDEO_RESOLUTION_4K",
  "model": "VEO_3_GENERATE_001",
  "aspect_ratio": "ASPECT_RATIO_16_9"
}

Response (200 OK)

{ "download_url": "https://cdn.autovideo.app/videos/4k/..." }
POST/ai/google/task/retry
Bearer Token

Thử lại các item bị lỗi

Tham số

Tham sốKiểuBắt buộcMô tả
requestsarrayMảng item cần retry
requests[].itemIdintegerItem ID
requests[].accountIdintegerAccount ID
requests[].modelstringModel key
recaptchaTokenstringToken reCAPTCHA

Request Body (JSON)

{
  "requests": [
    { "itemId": 10, "accountId": 5, "model": "VEO_3" }
  ]
}

Image AI

3 endpoints
POST/ai/google/image/generate
Bearer Token

Tạo hình ảnh AI từ văn bản (batch)

Tham số

Tham sốKiểuBắt buộcMô tả
accountIdintegerID tài khoản Google AI
recaptchaTokenstringToken reCAPTCHA
parentIdintegerItem ID cha
requestsarrayMảng yêu cầu (tối đa 50)
requests[].promptstringMô tả ảnh
requests[].modelstring`GEM_PIX_2` (Nano Banana Pro) | `NARWHAL` (Nano Banana 2) | `GEM_PIX` | `R2I` (Imagen 4)
requests[].aspectRatiostring`IMAGE_ASPECT_RATIO_PORTRAIT` | `IMAGE_ASPECT_RATIO_LANDSCAPE`
requests[].attachmentIdsinteger[]Ảnh tham chiếu

Request Body (JSON)

{
  "accountId": 5,
  "recaptchaToken": "03AFcWeA...",
  "requests": [
    {
      "prompt": "A photorealistic portrait of a woman in traditional Vietnamese áo dài",
      "model": "GEM_PIX_2",
      "aspectRatio": "IMAGE_ASPECT_RATIO_PORTRAIT"
    }
  ]
}

Response (200 OK)

{
  "data": [
    { "item_id": 20, "status": "pending", "prompt_text": "A photorealistic portrait..." }
  ]
}
POST/ai/google/image/edit
Bearer Token

Chỉnh sửa ảnh đã có bằng AI

Tham số

Tham sốKiểuBắt buộcMô tả
accountIdintegerID tài khoản Google AI
itemIdintegerItem ID ảnh nguồn (phải thuộc user)
promptstringMô tả chỉnh sửa
modelstringModel key
aspectRatiostringTỉ lệ khung hình
attachmentIdsinteger[]Ảnh tham chiếu bổ sung
seedintegerSeed

Request Body (JSON)

{
  "accountId": 5,
  "itemId": 20,
  "prompt": "Change the background to a cherry blossom garden",
  "model": "GEM_PIX_2",
  "aspectRatio": "IMAGE_ASPECT_RATIO_PORTRAIT"
}
POST/ai/google/image/download
Bearer Token

Kích hoạt upscale và tải ảnh

Tham số

Tham sốKiểuBắt buộcMô tả
item_idintegerItem ID ảnh
resolutionstring`IMAGE_RESOLUTION_ORIGINAL` | `IMAGE_RESOLUTION_2K` | `IMAGE_RESOLUTION_4K`

Request Body (JSON)

{ "item_id": 20, "resolution": "IMAGE_RESOLUTION_4K" }

Response (200 OK)

{ "download_url": "https://cdn.autovideo.app/images/4k/..." }

Audio & TTS

2 endpoints
GET/speech/voices
Bearer Token

Danh sách giọng đọc (có thể lọc)

Tham số

Tham sốKiểuBắt buộcMô tả
providerstring`ELEVENLABS` | `BYTEVOICE` | `SAMI`
languagesstring[]Mã ngôn ngữ: `vi`, `en`, `ja`…
gendersstring[]`male` | `female`
searchstringTìm kiếm theo tên giọng
pageintegerTrang (default: 1)
per_pageintegerSố kết quả / trang (tối đa 100)

Response (200 OK)

{
  "data": [
    {
      "voice_id": "21m00Tcm4TlvDq8ikWAM",
      "name": "Rachel",
      "provider": "ELEVENLABS",
      "gender": "female",
      "language": "en",
      "preview_url": "https://..."
    }
  ]
}
POST/speech/text-to-speech
Bearer Token

Chuyển văn bản thành giọng nói (batch, đa giọng)

Tham số

Tham sốKiểuBắt buộcMô tả
providerstring`ELEVENLABS` | `BYTEVOICE` | `SAMI`
providerModelstringModel cụ thể của provider
enableDialogueModebooleanBật chế độ hội thoại đa người
ttsarrayMảng đoạn thoại cần đọc
tts[].textstringNội dung văn bản
tts[].speakerNamestringTên người nói (dùng cho dialogue mode)
tts[].voiceIdstringVoice ID từ `/speech/voices`
tts[].voiceSettingsobjectĐiều chỉnh giọng (stability, similarity_boost, style, speed)

Request Body (JSON)

{
  "provider": "ELEVENLABS",
  "tts": [
    {
      "text": "Xin chào, tôi là trợ lý AI của AutoVideo.",
      "speakerName": "Host",
      "voiceId": "21m00Tcm4TlvDq8ikWAM",
      "voiceSettings": {
        "stability": 0.7,
        "similarity_boost": 0.8,
        "speed": 1.0
      }
    }
  ]
}

Response (200 OK)

{
  "task_id": 200,
  "status": "pending",
  "items": [
    { "item_id": 30, "status": "pending", "prompt_text": "Xin chào..." }
  ]
}

Tệp đính kèm

3 endpoints
POST/attachment/upload
Bearer Token

Upload file trực tiếp (multipart/form-data, tối đa 20 MB)

Tham số

Tham sốKiểuBắt buộcMô tả
filefileFile cần upload (ảnh, video, audio)

Response (200 OK)

{
  "attachment_id": 500,
  "url": "https://cdn.autovideo.app/attachments/abc123.jpg",
  "mime_type": "image/jpeg",
  "width": 1920,
  "height": 1080
}
POST/attachment/presign-upload
Bearer Token

Lấy presigned URL để upload trực tiếp lên S3/R2

Tham số

Tham sốKiểuBắt buộcMô tả
filenamestringTên file gốc
mimeTypestring`image/jpeg` | `image/png` | `video/mp4` | `audio/mpeg`…

Request Body (JSON)

{ "filename": "photo.jpg", "mimeType": "image/jpeg" }

Response (200 OK)

{
  "upload_url": "https://storage.r2.autovideo.app/?X-Amz-Signature=...",
  "path": "attachments/uuid/photo.jpg"
}
POST/attachment/confirm-upload
Bearer Token

Xác nhận hoàn tất upload (sau khi PUT lên presigned URL)

Tham số

Tham sốKiểuBắt buộcMô tả
pathstringPath từ presign response
filenamestringTên file gốc
filesizeintegerKích thước file (bytes, tối đa 20 MB)
file_hashstringMD5 / SHA256 của file
mime_typestringMIME type
widthintegerChiều rộng (ảnh/video)
heightintegerChiều cao

Request Body (JSON)

{
  "path": "attachments/uuid/photo.jpg",
  "filename": "photo.jpg",
  "filesize": 512000,
  "file_hash": "d41d8cd98f00b204e9800998ecf8427e",
  "mime_type": "image/jpeg",
  "width": 1920,
  "height": 1080
}

Response (200 OK)

{ "attachment_id": 501, "url": "https://cdn.autovideo.app/..." }

Google AI Account

6 endpoints
GET/account
Bearer Token

Danh sách tài khoản Google AI của user

Tham số

Tham sốKiểuBắt buộcMô tả
pageintegerTrang
per_pageintegerSố lượng / trang (max 100)

Response (200 OK)

{
  "data": [
    { "account_id": 5, "name": "Main Account", "project_id": "my-gcp-project", "is_primary": true }
  ]
}
POST/account/create
Bearer Token

Thêm tài khoản Google AI mới

Tham số

Tham sốKiểuBắt buộcMô tả
namestringTên hiển thị (max 255)
cookiestringGoogle session cookie
project_idstringGoogle Cloud Project ID
is_primarybooleanĐặt làm tài khoản chính

Request Body (JSON)

{
  "name": "Account Production",
  "cookie": "__Secure-1PSID=...",
  "project_id": "my-gcp-project-123",
  "is_primary": true
}

Response (200 OK)

{ "account_id": 6, "name": "Account Production", "is_primary": true }
GET/account/{accountId}/detail
Bearer Token

Chi tiết tài khoản Google AI

Tham số

Tham sốKiểuBắt buộcMô tả
accountIdintegerID tài khoản (path)
PUT/account/{accountId}/save
Bearer Token

Cập nhật thông tin tài khoản

Tham số

Tham sốKiểuBắt buộcMô tả
namestringTên mới
cookiestringCookie mới
project_idstringProject ID
is_primarybooleanĐặt là primary

Request Body (JSON)

{ "name": "Account Updated", "cookie": "__Secure-1PSID=...", "project_id": "gcp-123" }
DELETE/account/{accountId}/delete
Bearer Token

Xóa tài khoản Google AI

Tham số

Tham sốKiểuBắt buộcMô tả
accountIdintegerID tài khoản (path)

Response (200 OK)

{ "message": "Account deleted successfully" }
POST/ai/google/account/projects
Bearer Token

Lấy danh sách Google Cloud Projects từ cookie

Tham số

Tham sốKiểuBắt buộcMô tả
cookiestringGoogle session cookie để xác minh

Request Body (JSON)

{ "cookie": "__Secure-1PSID=..." }

Response (200 OK)

{
  "projects": [
    { "project_id": "my-gcp-project-123", "name": "My Project" }
  ]
}

Item Actions

2 endpoints
POST/ai/google/item/sort-order
Bearer Token

Cập nhật thứ tự sắp xếp các item

Tham số

Tham sốKiểuBắt buộcMô tả
item_idsinteger[]Mảng item_id theo thứ tự mới (vị trí trong mảng = sort_order)

Request Body (JSON)

{ "item_ids": [3, 1, 2, 5, 4] }

Response (200 OK)

{ "message": "Sort order updated" }
POST/ai/google/item/favorite
Bearer Token

Đánh dấu / bỏ đánh dấu item yêu thích

Tham số

Tham sốKiểuBắt buộcMô tả
item_idintegerID của item
is_favoriteboolean`true` để thêm, `false` để bỏ

Request Body (JSON)

{ "item_id": 10, "is_favorite": true }

Response (200 OK)

{ "message": "Updated", "item_id": 10, "is_favorite": true }

Cần hỗ trợ tích hợp?

Đội ngũ kỹ thuật của chúng tôi sẵn sàng hỗ trợ bạn xây dựng pipeline tạo video AI tự động.