Hợp đồng
- Base URL
- https://api.jencastudio.com
- Auth
- Authorization: Bearer jenca_sk_…
- Ảnh
- POST /v1/images — URL trong cùng response
- Video
- POST /v1/jobs — poll GET /v1/jobs/{id}
- Tính phí
- Credit. Khả dụng = balance − reserved
- Giới hạn
- 8 ảnh/phút · 8 job video/phút · 20 upload/phút
Tạo key trong Hồ sơ. Tối đa năm key đang dùng. Gửi key từ server. Route công khai là GET /v1/pricing và GET /v1/models. Key thiếu hoặc đã thu hồi trả 401.
Mỗi POST là một lần trừ credit. Ảnh lỗi được hoàn. Job video lỗi, hoặc job queued/running bị xóa, được trả phần đã giữ. Tạo giọng dùng số credit đã báo giá.
Tất cả endpoint
Mỗi hướng dẫn mở bằng method và path, rồi tham số và một request chạy được.
Tạo ảnh
Trừ credit, tạo ảnh và trả URL trong response này. Không có job. Kết nối giữ đến khi có ảnh: thường vài giây, tối đa khoảng 25 giây với model phải chờ upstream. Lỗi thì hoàn credit. POST /v1/jobs với model ảnh trả cùng body này.
| Field | Bắt buộc | Mô tả |
|---|
model | có | Id model ảnh từ GET /v1/models (type image) |
prompt | có | Nội dung cần tạo |
mode | không | t2i (mặc định) hoặc i2i. t2i kèm referenceImages được xử lý như i2i |
aspectRatio | không | Mặc định 16:9. Phải có trong caps của model |
resolution | không | Giá trị trong caps.resolutions, ví dụ 1k hoặc 2k |
referenceImages | i2i | URL upload của API này, hoặc https công khai |
quality | không | low, medium hoặc auto. Một số model Grok dùng field này |
Text to image
curl -X POST "https://api.jencastudio.com/v1/images" \
-H "Authorization: Bearer jenca_sk_…" \
-H "Content-Type: application/json" \
-d '{
"model": "google/nano-banana-2",
"prompt": "A glass perfume bottle on marble, soft window light, product photo",
"mode": "t2i",
"aspectRatio": "1:1",
"resolution": "1k"
}'
Edit
curl -X POST "https://api.jencastudio.com/v1/images" \
-H "Authorization: Bearer jenca_sk_…" \
-H "Content-Type: application/json" \
-d '{
"model": "google/nano-banana-2",
"prompt": "Same bottle on a dark wood table, keep the label",
"mode": "i2i",
"aspectRatio": "1:1",
"referenceImages": [
"https://api.jencastudio.com/media/uploads/12/6b1e.png"
]
}'
200 URL ảnh và số credit đã trừ.
{
"images": [
"https://api.jencastudio.com/media/images/12/9f3c.png"
],
"cost": 95
}
400 Thiếu field, không có giá, hoặc đây là model video.
{
"error": "Model không phải model ảnh — video dùng POST /v1/jobs"
}
402 Số dư khả dụng thấp hơn giá.
{
"error": "Số dư không đủ"
}
429 Vượt số lần trong một phút, hoặc hết luồng ảnh.
POST/v1/media/uploadBearerTải ảnh tham chiếu
Lưu JPEG, PNG, WebP hoặc GIF, tối đa 8MB. Truyền url trả về vào referenceImages. File được đọc từ storage, nên generator không cần tự tải một URL localhost.
| Field | Bắt buộc | Mô tả |
|---|
file | có | File ảnh. Tên field là file |
Request
curl -X POST "https://api.jencastudio.com/v1/media/upload" \
-H "Authorization: Bearer jenca_sk_…" \
-F "file=@product.png"
201 Đối tượng đã lưu.
{
"key": "uploads/12/6b1e.png",
"url": "https://api.jencastudio.com/media/uploads/12/6b1e.png",
"contentType": "image/png",
"size": 182331
}
400 Thiếu file, sai loại, hoặc quá 8MB.
Tạo job video
Model video giữ credit và trả job id. Poll GET /v1/jobs/{id} đến khi status là completed hoặc failed. Model ảnh trả URL ngay trong response, cùng body với POST /v1/images, không tạo job. i2v với từ hai ảnh được gửi dạng r2v. startend cần ảnh khung đầu, rồi ảnh khung cuối. motion cần một URL https MP4 công khai trong referenceVideos (20MB) và ít nhất một ảnh. /v1 không nhận upload video.
| Field | Bắt buộc | Mô tả |
|---|
model | có | Id model video |
prompt | có | Nội dung cần tạo |
mode | không | t2v (mặc định), i2v, r2v, startend hoặc motion |
duration | không | Ví dụ 5s. Phải khớp một dòng giá |
resolution | không | Ví dụ 720p hoặc 1080p |
aspectRatio | không | Mặc định 16:9 |
referenceImages | một số mode | URL ảnh |
referenceVideos | motion | Một URL video https công khai |
Text to video
curl -X POST "https://api.jencastudio.com/v1/jobs" \
-H "Authorization: Bearer jenca_sk_…" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance_2.0",
"prompt": "Slow push-in on a glass bottle, soft window light, no text",
"mode": "t2v",
"duration": "5s",
"resolution": "720p",
"aspectRatio": "16:9"
}'
Image to video
curl -X POST "https://api.jencastudio.com/v1/jobs" \
-H "Authorization: Bearer jenca_sk_…" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance_2.0",
"prompt": "The bottle turns a quarter to the left",
"mode": "i2v",
"duration": "5s",
"resolution": "720p",
"aspectRatio": "16:9",
"referenceImages": [
"https://api.jencastudio.com/media/uploads/12/6b1e.png"
]
}'
First and last frame
curl -X POST "https://api.jencastudio.com/v1/jobs" \
-H "Authorization: Bearer jenca_sk_…" \
-H "Content-Type: application/json" \
-d '{
"model": "veo-3.1",
"prompt": "The camera drifts from the wide shot onto the label",
"mode": "startend",
"duration": "6s",
"resolution": "720p",
"aspectRatio": "16:9",
"referenceImages": [
"https://api.jencastudio.com/media/uploads/12/start.png",
"https://api.jencastudio.com/media/uploads/12/end.png"
]
}'
200 Model ảnh. Cùng body với POST /v1/images. Không có job.
{
"images": [
"https://api.jencastudio.com/media/images/12/9f3c.png"
],
"cost": 95
}
201 Đã nhận job video. cost là credit đang giữ.
{
"jobId": 123,
"cost": 400
}
400 Thiếu field, không có giá, hoặc mode không hợp lệ.
{
"error": "model và prompt bắt buộc"
}
402 Số dư khả dụng thấp hơn giá.
{
"error": "Số dư không đủ"
}
Danh sách job
Mới nhất trước. Mỗi phần tử cùng dạng với GET /v1/jobs/{id}.
| Tham số | Vị trí | Bắt buộc | Mô tả |
|---|
limit | query | không | Mặc định 30. Tối đa 100. |
Request
curl -X GET "https://api.jencastudio.com/v1/jobs" \
-H "Authorization: Bearer jenca_sk_…"
Đọc một job
Poll vài giây một lần. Dừng khi completed hoặc failed. Path trong outputs thì ghép thêm base URL. queue_ahead có giá trị khi job đang chờ trong pool.
| Tham số | Vị trí | Bắt buộc | Mô tả |
|---|
id | path | có | Job id từ response tạo job. |
Request
curl -X GET "https://api.jencastudio.com/v1/jobs/123" \
-H "Authorization: Bearer jenca_sk_…"
200 Bản ghi job.
{
"job": {
"id": 123,
"model": "seedance_2.0",
"input_mode": "t2v",
"status": "completed",
"progress": 100,
"cost_credits": 400,
"outputs": [
"/media/relay/123.0.1760000000.sig"
],
"error": null,
"queue_ahead": null,
"params": {
"prompt": "Slow push-in on a glass bottle",
"mode": "t2v",
"duration": "5s",
"resolution": "720p",
"aspectRatio": "16:9"
},
"created_at": "2026-10-23 02:00:00",
"finished_at": "2026-10-23 02:01:12"
}
}
404 Key này không có job với id đó.
DELETE/v1/jobs/{id}BearerXóa job
Xóa job và file kết quả đã lưu. Job queued hoặc running được trả credit đã giữ.
| Tham số | Vị trí | Bắt buộc | Mô tả |
|---|
id | path | có | Job id. |
Request
curl -X DELETE "https://api.jencastudio.com/v1/jobs/123" \
-H "Authorization: Bearer jenca_sk_…"
200 Đã xóa.
{
"ok": true,
"id": 123
}
Số dư
balance là tổng sổ. reserved là credit đang giữ cho job video chưa xong. available là phần lần gọi tiếp theo được dùng.
Request
curl -X GET "https://api.jencastudio.com/v1/wallet" \
-H "Authorization: Bearer jenca_sk_…"
200 Ví.
{
"wallet": {
"balance": 10000,
"reserved": 400,
"available": 9600,
"updated_at": "2026-10-23 02:00:00"
}
}
Danh sách model
Model đang bán và đang bảo trì, kèm caps và giá công khai. Không trả giá vốn. Đọc caps trước khi gửi duration, resolution hoặc aspectRatio.
Request
curl -X GET "https://api.jencastudio.com/v1/models"
200 Catalog.
{
"models": [
{
"id": "google/nano-banana-2",
"name": "Nano Banana 2",
"type": "image",
"caps": {
"modes": [
"t2i",
"i2i"
],
"durations": [],
"resolutions": [
"1k"
],
"aspectRatios": [
"16:9",
"9:16",
"1:1"
]
},
"is_active": 1,
"is_maintenance": 0
}
],
"pricing": [
{
"id": 41,
"service_type": "image",
"model": "google/nano-banana-2",
"input_mode": "t2i",
"duration": null,
"resolution": "1k",
"price_unit": "per_call",
"sell_price": 95
}
]
}
Bảng giá
Giá tính bằng credit. Với mỗi model và mode, hàng là thời lượng, prices đi theo đúng thứ tự resolutions. Ô null là không bán.
Request
curl -X GET "https://api.jencastudio.com/v1/pricing"
200 Ma trận giá và danh sách phẳng.
{
"currency": "credit",
"models": [
{
"id": "seedance_2.0",
"name": "Seedance 2.0",
"type": "video",
"modes": [
{
"mode": "t2v",
"resolutions": [
"720p",
"1080p"
],
"rows": [
{
"duration": "5s",
"prices": [
400,
700
]
}
]
}
]
}
],
"pricing": []
}
GET/v1/voice/modelsBearerDanh sách model giọng trả phí
Jenca Free và VieNeu không có trong API.
| Tham số | Vị trí | Bắt buộc | Mô tả |
|---|
provider | query | có | elevenlabs | minimax |
Request
curl -X GET "https://api.jencastudio.com/v1/voice/models?provider=elevenlabs" \
-H "Authorization: Bearer jenca_sk_…"
200 Danh sách model giọng trả phí
{
"models": [
{
"model_id": "eleven_multilingual_v2",
"provider": "elevenlabs",
"name": "Multilingual v2"
}
]
}
400 Đầu vào sai hoặc provider không được hỗ trợ.
401 Thiếu thông tin xác thực, key sai hoặc đã thu hồi.
502 Yêu cầu tới dịch vụ giọng nói thất bại.
503 Dịch vụ giọng nói chưa sẵn sàng.
GET/v1/voice/voicesBearerDanh sách giọng
Dùng voice_id từ danh mục để tạo giọng. Đặt all=0 để lấy từng trang.
| Tham số | Vị trí | Bắt buộc | Mô tả |
|---|
provider | query | có | elevenlabs | minimax |
all | query | không | 0 | 1 (default: 1) |
page | query | không | ElevenLabs: 0+, MiniMax: 1+ |
page_size | query | không | 1–100 |
search | query | không | Từ khóa tìm kiếm. |
Request
curl -X GET "https://api.jencastudio.com/v1/voice/voices?provider=elevenlabs" \
-H "Authorization: Bearer jenca_sk_…"
200 Danh sách giọng
400 Đầu vào sai hoặc provider không được hỗ trợ.
401 Thiếu thông tin xác thực, key sai hoặc đã thu hồi.
502 Yêu cầu tới dịch vụ giọng nói thất bại.
503 Dịch vụ giọng nói chưa sẵn sàng.
GET/v1/voice/languagesBearerDanh sách ngôn ngữ
Dùng mã ngôn ngữ của provider đã chọn.
| Tham số | Vị trí | Bắt buộc | Mô tả |
|---|
provider | query | có | elevenlabs | minimax |
Request
curl -X GET "https://api.jencastudio.com/v1/voice/languages?provider=elevenlabs" \
-H "Authorization: Bearer jenca_sk_…"
200 Danh sách ngôn ngữ
400 Đầu vào sai hoặc provider không được hỗ trợ.
401 Thiếu thông tin xác thực, key sai hoặc đã thu hồi.
502 Yêu cầu tới dịch vụ giọng nói thất bại.
POST/v1/voice/quoteBearerBáo giá TTS
Trả giá và số dư khả dụng, không trừ credit.
| Field | Bắt buộc | Mô tả |
|---|
provider | có | elevenlabs | minimax |
modelId | có | ID model từ danh mục. |
text | có | Văn bản tối đa 20.000 ký tự. |
exportTranscript | không | Yêu cầu bản chép lời SRT. |
ElevenLabs
curl -X POST "https://api.jencastudio.com/v1/voice/quote" \
-H "Authorization: Bearer jenca_sk_…" \
-H "Content-Type: application/json" \
-d '{
"provider": "elevenlabs",
"modelId": "eleven_multilingual_v2",
"text": "Xin chào!"
}'
200 Giá tính bằng credit.
{
"characters": 9,
"modelId": "eleven_multilingual_v2",
"provider": "elevenlabs",
"exportTranscript": false,
"sellCredits": 6,
"available": 1000,
"enough": true
}
400 Đầu vào sai hoặc provider không được hỗ trợ.
401 Thiếu thông tin xác thực, key sai hoặc đã thu hồi.
Tạo giọng nói
Mỗi yêu cầu được nhận tạo một job tính phí. Dùng job.id để kiểm tra kết quả.
| Field | Bắt buộc | Mô tả |
|---|
provider | có | elevenlabs | minimax |
modelId | có | ID model từ danh mục. |
text | có | Văn bản tối đa 20.000 ký tự. |
exportTranscript | không | Yêu cầu bản chép lời SRT. |
voiceId | có | ID giọng từ danh mục. |
languageCode | có | Mã ngôn ngữ từ danh mục. |
voiceSettings | không | Đối tượng cấu hình riêng của provider. |
name | không | Tên job. |
confirmSellCredits | không | Số credit dự kiến từ báo giá. |
ElevenLabs
curl -X POST "https://api.jencastudio.com/v1/voice/tts" \
-H "Authorization: Bearer jenca_sk_…" \
-H "Content-Type: application/json" \
-d '{
"provider": "elevenlabs",
"modelId": "eleven_multilingual_v2",
"text": "Xin chào!",
"voiceId": "VOICE_ID",
"languageCode": "vi"
}'
202 Job đã được nhận.
{
"job": {
"id": 123,
"provider": "elevenlabs",
"modelId": "eleven_multilingual_v2",
"text": "Xin chào!",
"voiceId": "VOICE_ID",
"languageCode": "vi",
"status": "pending",
"progress": 5,
"characters": 9,
"sellCredits": 6,
"audioUrl": null,
"expiresAt": null,
"expired": false,
"error": null,
"exportTranscript": false,
"transcriptSrt": null,
"createdAt": "2026-11-18 10:00:00",
"finishedAt": null
},
"quote": {
"characters": 9,
"modelId": "eleven_multilingual_v2",
"provider": "elevenlabs",
"exportTranscript": false,
"sellCredits": 6
},
"available": 994
}
400 Đầu vào sai hoặc provider không được hỗ trợ.
401 Thiếu thông tin xác thực, key sai hoặc đã thu hồi.
402 Không đủ credit.
403 Tài khoản bị giới hạn quyền sử dụng.
409 Giá đã đổi. Xem báo giá mới trước khi gửi lại.
429 Vượt giới hạn gọi. Chờ theo Retry-After.
502 Yêu cầu tới dịch vụ giọng nói thất bại.
503 Dịch vụ giọng nói chưa sẵn sàng.
GET/v1/voice/tts/{id}BearerLấy kết quả tạo giọng
Kiểm tra đến khi job hoàn thành hoặc thất bại. Khi hoàn thành, tải audio từ audioUrl.
| Tham số | Vị trí | Bắt buộc | Mô tả |
|---|
id | path | có | job.id |
Request
curl -X GET "https://api.jencastudio.com/v1/voice/tts/123" \
-H "Authorization: Bearer jenca_sk_…"
200 Trạng thái hiện tại của job.
{
"job": {
"id": 123,
"provider": "elevenlabs",
"modelId": "eleven_multilingual_v2",
"text": "Xin chào!",
"voiceId": "VOICE_ID",
"languageCode": "vi",
"status": "completed",
"progress": 100,
"characters": 9,
"sellCredits": 6,
"audioUrl": "https://api.jencastudio.com/media/voice/12/123.mp3",
"expiresAt": null,
"expired": false,
"error": null,
"exportTranscript": false,
"transcriptSrt": null,
"createdAt": "2026-11-18 10:00:00",
"finishedAt": "2026-11-18 10:00:05"
},
"available": 994
}
400 Đầu vào sai hoặc provider không được hỗ trợ.
401 Thiếu thông tin xác thực, key sai hoặc đã thu hồi.
404 Không tìm thấy job.
502 Yêu cầu tới dịch vụ giọng nói thất bại.
503 Dịch vụ giọng nói chưa sẵn sàng.