Trên trang này
Jenca Studio
Vào studio

APIHợp đồng

Sổ tay Jenca

Cẩm nang API,ảnh trả ngay, video qua job.

Phiên bản 1. Ảnh trả trong chính response của lần gọi. Video trả job id để poll. Đơn vị tính là credit. Id model và giá lấy từ catalog.

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.

POST/v1/imagesBearer

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.

FieldBắt buộcMô tả
modelcóId model ảnh từ GET /v1/models (type image)
promptcóNội dung cần tạo
modekhôngt2i (mặc định) hoặc i2i. t2i kèm referenceImages được xử lý như i2i
aspectRatiokhôngMặc định 16:9. Phải có trong caps của model
resolutionkhôngGiá trị trong caps.resolutions, ví dụ 1k hoặc 2k
referenceImagesi2iURL upload của API này, hoặc https công khai
qualitykhônglow, medium hoặc auto. Một số model Grok dùng field này

Text to image

cURL
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
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ừ.

JSON
{
  "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.

JSON
{
  "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á.

JSON
{
  "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/uploadBearer

Tả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.

FieldBắt buộcMô tả
filecóFile ảnh. Tên field là file

Request

cURL
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.

JSON
{
  "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.

POST/v1/jobsBearer

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.

FieldBắt buộcMô tả
modelcóId model video
promptcóNội dung cần tạo
modekhôngt2v (mặc định), i2v, r2v, startend hoặc motion
durationkhôngVí dụ 5s. Phải khớp một dòng giá
resolutionkhôngVí dụ 720p hoặc 1080p
aspectRatiokhôngMặc định 16:9
referenceImagesmột số modeURL ảnh
referenceVideosmotionMột URL video https công khai

Text to video

cURL
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
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
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.

JSON
{
  "images": [
    "https://api.jencastudio.com/media/images/12/9f3c.png"
  ],
  "cost": 95
}

201 Đã nhận job video. cost là credit đang giữ.

JSON
{
  "jobId": 123,
  "cost": 400
}

400 Thiếu field, không có giá, hoặc mode không hợp lệ.

JSON
{
  "error": "model và prompt bắt buộc"
}

402 Số dư khả dụng thấp hơn giá.

JSON
{
  "error": "Số dư không đủ"
}
GET/v1/jobsBearer

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ộcMô tả
limitquerykhôngMặc định 30. Tối đa 100.

Request

cURL
curl -X GET "https://api.jencastudio.com/v1/jobs" \
  -H "Authorization: Bearer jenca_sk_…"

200 Danh sách job.

JSON
{
  "jobs": []
}
GET/v1/jobs/{id}Bearer

Đọ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ộcMô tả
idpathcóJob id từ response tạo job.

Request

cURL
curl -X GET "https://api.jencastudio.com/v1/jobs/123" \
  -H "Authorization: Bearer jenca_sk_…"

200 Bản ghi job.

JSON
{
  "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 đó.

JSON
{
  "error": "Not found"
}
DELETE/v1/jobs/{id}Bearer

Xó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ộcMô tả
idpathcóJob id.

Request

cURL
curl -X DELETE "https://api.jencastudio.com/v1/jobs/123" \
  -H "Authorization: Bearer jenca_sk_…"

200 Đã xóa.

JSON
{
  "ok": true,
  "id": 123
}

404 Không thấy job.

JSON
{
  "error": "Not found"
}
GET/v1/walletBearer

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
curl -X GET "https://api.jencastudio.com/v1/wallet" \
  -H "Authorization: Bearer jenca_sk_…"

200 Ví.

JSON
{
  "wallet": {
    "balance": 10000,
    "reserved": 400,
    "available": 9600,
    "updated_at": "2026-10-23 02:00:00"
  }
}
GET/v1/modelsPublic

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
curl -X GET "https://api.jencastudio.com/v1/models"

200 Catalog.

JSON
{
  "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
    }
  ]
}
GET/v1/pricingPublic

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
curl -X GET "https://api.jencastudio.com/v1/pricing"

200 Ma trận giá và danh sách phẳng.

JSON
{
  "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/modelsBearer

Danh sách model giọng trả phí

Jenca Free và VieNeu không có trong API.

Tham sốVị tríBắt buộcMô tả
providerquerycóelevenlabs | minimax

Request

cURL
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í

JSON
{
  "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/voicesBearer

Danh 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ộcMô tả
providerquerycóelevenlabs | minimax
allquerykhông0 | 1 (default: 1)
pagequerykhôngElevenLabs: 0+, MiniMax: 1+
page_sizequerykhông1–100
searchquerykhôngTừ khóa tìm kiếm.

Request

cURL
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/languagesBearer

Danh sách ngôn ngữ

Dùng mã ngôn ngữ của provider đã chọn.

Tham sốVị tríBắt buộcMô tả
providerquerycóelevenlabs | minimax

Request

cURL
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/quoteBearer

Báo giá TTS

Trả giá và số dư khả dụng, không trừ credit.

FieldBắt buộcMô tả
providercóelevenlabs | minimax
modelIdcóID model từ danh mục.
textcóVăn bản tối đa 20.000 ký tự.
exportTranscriptkhôngYêu cầu bản chép lời SRT.

ElevenLabs

cURL
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.

JSON
{
  "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.

POST/v1/voice/ttsBearer

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ả.

FieldBắt buộcMô tả
providercóelevenlabs | minimax
modelIdcóID model từ danh mục.
textcóVăn bản tối đa 20.000 ký tự.
exportTranscriptkhôngYêu cầu bản chép lời SRT.
voiceIdcóID giọng từ danh mục.
languageCodecóMã ngôn ngữ từ danh mục.
voiceSettingskhôngĐối tượng cấu hình riêng của provider.
namekhôngTên job.
confirmSellCreditskhôngSố credit dự kiến từ báo giá.

ElevenLabs

cURL
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.

JSON
{
  "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}Bearer

Lấ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ộcMô tả
idpathcójob.id

Request

cURL
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.

JSON
{
  "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.