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 yêu cầu API token trong header Authorization. Token được tạo trong giao diện — không cần gọi API đăng nhập.

  1. 1Đăng nhập vào app.autovideo.app
  2. 2Nhấn vào avatar góc trái → chọn tab API Tokens
  3. 3Nhấn Tạo API token mới, đặt tên token, nhấn xác nhận
  4. 4Sao chép token ngay — token chỉ hiển thị một lần
Authorization Header
Authorization: Bearer 1|AbCdEfGhIjKlMnOpQrStUvWxYz1234567890ab

Đị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

1 endpoints
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"
}

Task

7 endpoints
GET/task/list
Bearer Token

Danh sách task của user (phân trang)

Tham số

Tham sốKiểuBắt buộcMô tả
pageintegerTrang hiện tại (default: 1)

Response (200 OK)

{
  "data": [
    { "task_id": 100, "status": "completed", "item_count": 5, "created_at": "2025-01-01T00:00:00Z" }
  ],
  "meta": { "current_page": 1, "total": 20 }
}
GET/task/items
Bearer Token

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

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_3_GENERATE_001",
  "aspect_ratio": "ASPECT_RATIO_16_9",
  "output_url": "https://cdn.autovideo.app/...",
  "thumbnail_url": "https://cdn.autovideo.app/..."
}
GET/task/{taskId}/detail
Bearer Token

Chi tiết đầy đủ của một task kèm toàn bộ items

Tham số

Tham sốKiểuBắt buộcMô tả
taskIdintegerID của task (path parameter)
POST/task/check
Bearer Token

Kiểm tra trạng thái nhiều video/image 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", "error_message": "..." }
  ]
}
POST/task/check-tts
Bearer Token

Kiểm tra trạng thái các TTS item (polling riêng cho audio)

Tham số

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

Request Body (JSON)

{ "item_ids": [30, 31] }
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 nào)

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, tối đa 50 item)

Tham số

Tham sốKiểuBắt buộcMô tả
generationModestring`TEXT_TO_VIDEO` | `IMAGE_TO_VIDEO` | `REFERENCE_TO_VIDEO`
recaptchaTokenstringToken reCAPTCHA
projectIdstringGoogle Cloud Project ID (ghi đè project mặc định)
parentIdintegerItem ID cha nếu thêm vào task đang có
requestsarrayMảng yêu cầu tạo video (1 – 50)
requests[].promptstringMô tả nội dung video
requests[].modelstringModel key: `Veo 3.1 - Lite`, `Veo 3.1 - Lite [Lower Priority]`, `Veo 3.1 - Fast`, `Veo 3.1 - Fast [Lower Priority]`, `Veo 3.1 - Quality`, `Veo 2 - Fast`, `Veo 2 - Quality`, `GROK_AURORA`
requests[].aspectRatiostring`VIDEO_ASPECT_RATIO_LANDSCAPE` | `VIDEO_ASPECT_RATIO_PORTRAIT`
requests[].attachmentIdsinteger[]Attachment ID ảnh đầu vào (cho image-to-video / reference)
requests[].durationintegerĐộ dài video: `4` | `6` | `8` (giây)
requests[].seedintegerSeed (1 – 99999) để tái tạo kết quả
requests[].voiceobjectGiọng đọc cho video: `{ mediaId: string }`
requests[].promptPartsarrayPrompt có tham chiếu ảnh: `[{ type: 'text'|'reference', text?, attachmentId?, label? }]`

Request Body (JSON)

{
  "generationMode": "TEXT_TO_VIDEO",
  "recaptchaToken": "03AFcWeA...",
  "requests": [
    {
      "prompt": "A cinematic shot of waves crashing on shore at golden hour",
      "model": "Veo 3.1 - Fast",
      "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE",
      "duration": 8
    },
    {
      "prompt": "Cherry blossoms falling in slow motion",
      "model": "Veo 3.1 - Fast",
      "aspectRatio": "VIDEO_ASPECT_RATIO_PORTRAIT",
      "seed": 12345
    }
  ]
}

Response (200 OK)

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

Kéo dài video hiện có từ một frame xác định

Tham số

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

Request Body (JSON)

{
  "accountId": 5,
  "itemId": 10,
  "prompt": "The camera slowly pans right revealing mountains",
  "startFrameIndex": 0,
  "endFrameIndex": 24,
  "videoModelKey": "Veo 3.1 - Fast",
  "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE"
}

Response (200 OK)

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

Tạo đoạn chuyển tiếp (jump cut) từ một frame của video

Tham số

Tham sốKiểuBắt buộcMô tả
itemIdintegerItem ID video nguồn (phải thuộc user)
promptstringMô tả cảnh mới sau jump
startFrameIndexintegerFrame bắt đầu jump (≥ 0)
videoModelKeystringModel key
aspectRatiostringTỉ lệ khung hình
seedintegerSeed ngẫu nhiên (≥ 1)
recaptchaTokenstringToken reCAPTCHA

Request Body (JSON)

{
  "itemId": 10,
  "prompt": "A close-up of a blooming flower",
  "startFrameIndex": 48,
  "videoModelKey": "Veo 3.1 - Fast",
  "aspectRatio": "VIDEO_ASPECT_RATIO_LANDSCAPE"
}

Response (200 OK)

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

Ghép nhiều video thành một (≥ 2 clip)

Tham số

Tham sốKiểuBắt buộcMô tả
inputVideosarrayMảng ≥ 2 video cần ghép (theo thứ tự)
inputVideos[].itemIdintegerItem ID video (status phải là completed)
inputVideos[].lengthNanosintegerĐộ dài clip tính bằng nanoseconds
inputVideos[].startTimeOffsetstringThời điểm bắt đầu cắt, e.g. `0s`
inputVideos[].endTimeOffsetstringThời điểm kết thúc cắt, 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/task/retry
Bearer Token

Thử lại các item bị lỗi (failed) hoặc đã hoàn thành (completed)

Tham số

Tham sốKiểuBắt buộcMô tả
requestsarrayMảng item cần retry
requests[].itemIdintegerItem ID cần retry
requests[].modelstringModel key sử dụng lại (có thể đổi model)
recaptchaTokenstringToken reCAPTCHA

Request Body (JSON)

{
  "requests": [
    { "itemId": 10, "model": "Veo 3.1 - Fast" },
    { "itemId": 11, "model": "GROK_AURORA" }
  ]
}

Response (200 OK)

{
  "data": [
    { "item_id": 10, "status": "pending", "model": "Veo 3.1 - Fast" },
    { "item_id": 11, "status": "pending", "model": "GROK_AURORA" }
  ]
}

Image AI

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

Tạo hình ảnh AI từ văn bản hoặc ảnh tham chiếu (batch, tối đa 50)

Tham số

Tham sốKiểuBắt buộcMô tả
recaptchaTokenstringToken reCAPTCHA
parentIdintegerItem ID cha nếu thêm vào task đang có
requestsarrayMảng yêu cầu (1 – 50)
requests[].promptstringMô tả ảnh cần tạo
requests[].modelstring`GEM_PIX_2` | `NARWHAL` | `GEM_PIX` | `R2I` | `GROK_IMAGE`
requests[].aspectRatiostring`IMAGE_ASPECT_RATIO_PORTRAIT` | `IMAGE_ASPECT_RATIO_LANDSCAPE`
requests[].attachmentIdsinteger[]Ảnh tham chiếu phong cách / nội dung
requests[].seedintegerSeed (1 – 99999) để tái tạo kết quả

Request Body (JSON)

{
  "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",
      "seed": 42
    }
  ]
}

Response (200 OK)

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

Chỉnh sửa ảnh hiện có bằng AI (image-to-image)

Tham số

Tham sốKiểuBắt buộcMô tả
accountIdintegerID tài khoản AI dùng để xử lý
itemIdintegerItem ID ảnh nguồn (phải thuộc user)
promptstringMô tả chỉnh sửa cần thực hiện
modelstringModel key
aspectRatiostring`IMAGE_ASPECT_RATIO_PORTRAIT` | `IMAGE_ASPECT_RATIO_LANDSCAPE`
attachmentIdsinteger[]Ảnh tham chiếu bổ sung
seedintegerSeed ngẫu nhiên (≥ 1)
recaptchaTokenstringToken reCAPTCHA

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"
}

Response (200 OK)

{ "item_id": 21, "status": "pending", "generation_mode": "EDIT_IMAGE" }
POST/ai/google/download
Bearer Token

Kích hoạt upscale / tải xuống hàng loạt (video và ảnh)

Tham số

Tham sốKiểuBắt buộcMô tả
itemsarrayMảng item cần download (1 – 50)
items[].item_idintegerItem ID cần tải
items[].resolutionstringVideo: `VIDEO_RESOLUTION_ORIGINAL` | `VIDEO_RESOLUTION_1080P` | `VIDEO_RESOLUTION_4K` — Ảnh: `IMAGE_RESOLUTION_ORIGINAL` | `IMAGE_RESOLUTION_2K` | `IMAGE_RESOLUTION_4K`

Request Body (JSON)

{
  "items": [
    { "item_id": 10, "resolution": "VIDEO_RESOLUTION_4K" },
    { "item_id": 20, "resolution": "IMAGE_RESOLUTION_2K" }
  ]
}

Response (200 OK)

{ "message": "Download jobs dispatched", "count": 2 }

Audio & TTS

2 endpoints
GET/speech/voices
Bearer Token

Danh sách giọng đọc (nhiều bộ lọc)

Tham số

Tham sốKiểuBắt buộcMô tả
providerstringLọc theo provider, e.g. `ELEVENLABS`
languagesstring[]Mã ngôn ngữ: `vi`, `en`, `ja`…
gendersstring[]`male` | `female`
categoriesstring[]Loại giọng, e.g. `narration`, `conversational`
agesstring[]Nhóm tuổi: `young` | `middle_aged` | `old`
use_casesstring[]Use case: `news` | `audiobook` | `social_media`…
qualitystring`hq` | `any`
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://..."
    }
  ],
  "meta": { "current_page": 1, "total": 350 }
}
POST/speech/text-to-speech
Bearer Token

Chuyển văn bản thành giọng nói (hỗ trợ đa người nói)

Tham số

Tham sốKiểuBắt buộcMô tả
modelstring`11LABS_V2` | `11LABS_V2.5` | `11LABS_V3`
voiceSettingsobjectCài đặt giọng toàn cục
voiceSettings.voiceStylestring`Expressive` | `Neutral` | `Consistent`
voiceSettings.speednumberTốc độ đọc: 0.25 – 4.0
voiceSettings.similarityintegerĐộ tương đồng giọng: 0 – 100
segmentsarrayMảng đoạn thoại (≥ 1)
segments[].voiceIdstringVoice ID từ `/speech/voices`
segments[].speakerNamestringTên người nói (tối đa 100 ký tự)
segments[].textstringNội dung văn bản (tối đa 5000 ký tự)

Request Body (JSON)

{
  "model": "11LABS_V2.5",
  "voiceSettings": {
    "voiceStyle": "Expressive",
    "speed": 1.0,
    "similarity": 75
  },
  "segments": [
    {
      "voiceId": "21m00Tcm4TlvDq8ikWAM",
      "speakerName": "Host",
      "text": "Xin chào, tôi là trợ lý AI của AutoVideo."
    },
    {
      "voiceId": "AZnzlk1XvdvUeBnXmlld",
      "speakerName": "Guest",
      "text": "Chào bạn! Hôm nay chúng ta sẽ tạo video gì?"
    }
  ]
}

Response (200 OK)

{
  "task_id": 300,
  "status": "pending",
  "items": [
    { "item_id": 30, "status": "pending", "prompt_text": "Xin chào..." },
    { "item_id": 31, "status": "pending", "prompt_text": "Chào bạn!..." }
  ]
}

Tệp đính kèm

2 endpoints
POST/attachment/presign-upload
Bearer Token

Lấy presigned URL để upload trực tiếp lên R2/S3 (khuyến nghị cho file lớn)

Tham số

Tham sốKiểuBắt buộcMô tả
filenamestringTên file gốc
mimeTypestring`image/jpeg` | `image/png` | `image/webp` | `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 file lên presigned URL

Tham số

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

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/..." }

AI Account

6 endpoints
GET/account
Bearer Token

Danh sách tài khoản AI của user (Google, Grok, ChatGPT…)

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, "provider": "google", "name": "Main Account", "project_id": "my-gcp-project", "is_primary": true }
  ]
}
POST/account/create
Bearer Token

Thêm tài khoản AI mới (Google / Grok / ChatGPT)

Tham số

Tham sốKiểuBắt buộcMô tả
providerstring`google` | `grok` | `chatgpt`
namestringTên hiển thị (max 255)
cookiestringSession cookie (bắt buộc với Google và Grok, không cần với ChatGPT)
access_tokenstringAccess token (dùng thay cookie cho ChatGPT)
project_idstringGoogle Cloud Project ID (bắt buộc với provider `google`)
is_primarybooleanĐặt làm tài khoản chính
is_sharedbooleanCho phép dùng chung tài khoản

Request Body (JSON)

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

Response (200 OK)

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

Chi tiết tài khoản 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 AI

Tham số

Tham sốKiểuBắt buộcMô tả
namestringTên mới
cookiestringCookie mới (bắt buộc với Google / Grok)
project_idstringGoogle Cloud Project ID (bắt buộc với Google)
is_primarybooleanĐặt là primary
is_sharedbooleanCho phép dùng chung
proxystringProxy string, e.g. `host:port:user:pass` (tối đa 500 ký tự)

Request Body (JSON)

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

Xóa tài khoản 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ừ session cookie

Tham số

Tham sốKiểuBắt buộcMô tả
cookiestringGoogle session cookie để xác minh và liệt kê projects

Request Body (JSON)

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

Response (200 OK)

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

Item Actions

3 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í index = sort_order mới)

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 yêu thích một item

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 }
POST/ai/google/item/favorite/batch
Bearer Token

Đánh dấu / bỏ đánh dấu yêu thích hàng loạt item

Tham số

Tham sốKiểuBắt buộcMô tả
item_idsinteger[]Mảng item_id cần cập nhật
is_favoriteboolean`true` để thêm, `false` để bỏ

Request Body (JSON)

{ "item_ids": [10, 11, 12], "is_favorite": true }

Response (200 OK)

{ "message": "Updated", "count": 3 }

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.