sangtao.ai
API key

Jobs

Lấy một job

Một job: trạng thái và tiến độ khi đang chạy, kết quả khi xong.

GEThttps://api.sangtao.ai/v2/jobs/{jobId}

Xác thực

  • X-Api-Keystring · headerbắt buộc

    API key của bạn, tạo ở trang API key trong tài khoản.

Tham số đường dẫn

  • jobIdstringbắt buộc

    jobId trong đường dẫn.

Mọi endpoint tạo job — GPT Image (POST /images/generations) — đều trả về jobId. Poll endpoint này để theo dõi tiến độ và lấy kết quả.

Với job ảnh, GET /images/generations/{jobId} trả đúng response này — dùng đường nào cũng được. Đường đó chỉ tìm job ảnh: job loại khác trả 404 JOB_NOT_FOUND.

Luồng xử lý

Trạng tháiMô tảHành động
pendingJob đang chờ trong queueTiếp tục poll
processingĐang xử lý, có progress updatesHiện progress bar
completeHoàn thành! Kết quả trong resultUrl / resultImagesHiển thị kết quả
errorLỗi. Thông báo trong trường errorHiện lỗi + tùy chọn thử lại

Job GPT Image bắt đầu ở "WaitingForAgent" (đang chờ máy), không phải "pending" — xử lý như pending và tiếp tục poll.

Các trường response

jobIdstring

ID duy nhất của job

typestring

Loại job: "AgentJob" cho GPT Image, "RenderVideo" cho render tuỳ chỉnh. Cùng giá trị bộ lọc type của GET /jobs nhận.

categorystring

Nhóm của loại job, ví dụ "agent".

typeDisplayNamestring

Tên loại job để hiển thị, ví dụ "Agent Job".

titlestring

Tiêu đề của job. null với job không có tiêu đề — job ảnh không có.

promptstring

Prompt bạn đã gửi. Có trong danh sách (GET /jobs); ở đây là null — đọc params.prompt.

statusstring

"WaitingForAgent" | "processing" | "complete" | "error". So sánh không phân biệt hoa thường — endpoint này trả chữ thường trong khi vài chỗ khác trả "Complete".

progressnumber

0 đến 100. Đo thực tế: giữ nguyên 0 cho tới khi job xong, nên không dùng làm thanh tiến độ được.

stepstring

Bước hiện tại của job nhiều bước. Job ảnh luôn null.

resultUrlstring

Ảnh hoặc video đã xong, trước đó là null. Link sống bảy ngày — cần giữ lâu hơn thì tải về lưu phía bạn.

resultImagesstring[]

Cùng kết quả đó dạng mảng.

resultDataobject

Chi tiết kết quả — resultUrl, imageUrls (mảng), width, height và durationMs (số), và thumbnailUrl khi job có ảnh thu nhỏ.

thumbnailUrlstring

Ảnh thu nhỏ, cho job video.

hasDownloadableAssetsboolean

true khi job có file để tải về.

queuePositionnumber

Khi job đang chờ máy: số job chưa được máy nhận đang đứng trước nó (0 = kế tiếp). null khi đã chạy hoặc đã xong.

etaSecondsnumber

Khi đang chờ: còn khoảng bao nhiêu giây thì máy bắt đầu chạy. null khi chưa đủ dữ liệu, hoặc khi đã chạy.

etaCompleteSecondsnumber

Khi đang chờ hoặc đang chạy: còn khoảng bao nhiêu giây thì có kết quả. null khi chưa đủ dữ liệu, hoặc khi đã xong.

errorstring

Lý do hỏng, viết cho người đọc. null nếu không hỏng.

failureKindstring

Mã lỗi để code xử lý. Đây là trường quyết định retry có ích hay không.

elapsedSecondsnumber

Thời gian chạy. Đo thử một ảnh đơn giản mất khoảng 13 giây.

creditCostnumber

Đã quyết toán thì là số thực trừ. Job hỏng được hoàn tự động nên là 0. Khi job còn chạy là số credit đang khoá. Bằng 0 nếu gói tháng đã trả.

paramsobject

Những gì bạn đã gửi, để đối chiếu. Job ảnh chỉ gồm các trường bạn gửi, đúng kiểu (số, true/false, mảng); referenceImages là các link gốc bạn gửi.

createdAtstring

Lúc nhận job; processingAt là lúc máy bắt đầu; completedAt là lúc xong.

modelstring

Tên model đúng như bạn gửi, ví dụ "gpt-image-latest".

resolvedModelstring

Model đã chạy job, ví dụ "gpt-image-2.6" — chốt lúc tạo job.

serverstring

Server đã chạy job: "standard".

retryCountnumber

Số lần hệ thống tự thử lại. Không phải thứ bạn điều khiển.

webhookobject

Chỉ có khi request gửi webhookUrl: kết quả lần giao gần nhất. Không nằm trong data của webhook

Ví dụ response

Đang xử lý:

json
{
  "success": true,
  "data": {
    "jobId": "acff47cbfacf4e27bbc08770c9ea246d",
    "type": "AgentJob",
    "status": "processing",
    "progress": 0,
    "step": null,
    "queuePosition": null,
    "etaSeconds": null,
    "etaCompleteSeconds": 25
  }
}

Hoàn thành:

json
{
  "success": true,
  "data": {
    "jobId": "acff47cbfacf4e27bbc08770c9ea246d",
    "type": "AgentJob",
    "category": "agent",
    "typeDisplayName": "Agent Job",
    "title": null,
    "prompt": null,
    "status": "complete",
    "progress": 100.0,
    "resultUrl": "https://cdn.sangtao.ai/agent-jobs/acff47cb.../fa3c91.png",
    "resultImages": [
      "https://cdn.sangtao.ai/agent-jobs/acff47cb.../fa3c91.png"
    ],
    "resultData": {
      "resultUrl": "https://cdn.sangtao.ai/agent-jobs/acff47cb.../fa3c91.png",
      "imageUrls": [
        "https://cdn.sangtao.ai/agent-jobs/acff47cb.../fa3c91.png"
      ],
      "width": 1024,
      "height": 1024,
      "durationMs": 13100
    },
    "error": null,
    "failureKind": null,
    "hasDownloadableAssets": true,
    "queuePosition": null,
    "etaSeconds": null,
    "etaCompleteSeconds": null,
    "elapsedSeconds": 13.1,
    "creditCost": 0.0,
    "createdAt": "2026-09-19T09:42:59Z",
    "processingAt": "2026-09-19T09:43:17Z",
    "completedAt": "2026-09-19T09:43:30Z",
    "model": "gpt-image-latest",
    "resolvedModel": "gpt-image-2.6",
    "server": "standard"
  }
}

Lỗi:

json
{
  "success": true,
  "data": {
    "jobId": "acff47cbfacf4e27bbc08770c9ea246d",
    "status": "error",
    "step": null,
    "failureKind": "PROMPT_UNCLEAR",
    "error": "The prompt is not clear enough to create an image. Describe the image you want more specifically.",
    "creditCost": 0
  }
}

Khi request có webhookUrl, có thêm:

json
{
  "webhook": {
    "url": "https://example.com/webhooks/sangtao",
    "status": "succeeded",
    "attemptCount": 1,
    "lastHttpStatus": 200,
    "lastError": null,
    "deliveryId": "dlv_7Fz2kWq4N"
  }
}

Mã lỗi

MãerrorCodeKhi nào
404JOB_NOT_FOUNDKhông có job nào của bạn với jobId này

Job hỏng không phải lỗi của lượt gọi này: vẫn trả 200 với status "error" (như trên).

Tần suất poll

Chờ khoảng mười giây trước lần poll đầu — không job nào xong nhanh hơn thế, nên poll ngay lập tức lúc nào cũng nhận về "chưa xong".

Loại jobTần suất khuyên nghịThời gian thường mất
GPT Image5 giây30–90 giây

Ví dụ đầy đủ

for i in $(seq 60); do
  R=$(curl -sS https://api.sangtao.ai/v2/jobs/$JOB \
    -H "X-Api-Key: YOUR_KEY")
  S=$(echo "$R" | jq -r '.data.status' | tr 'A-Z' 'a-z')

  [ "$S" = "complete" ] && {
    echo "$R" | jq -r '.data.resultUrl'; break
  }
  [ "$S" = "error" ] && {
    echo "$R" | jq -r '.data.error'; break
  }
  sleep 5
done
GET/jobs/{jobId}
curl "https://api.sangtao.ai/v2/jobs/acff47cbfacf4e27bbc08770c9ea246d" \
  -H "X-Api-Key: YOUR_API_KEY"
{
  "success": true,
  "data": {
    "jobId": "acff47cbfacf4e27bbc08770c9ea246d",
    "type": "AgentJob",
    "category": "agent",
    "typeDisplayName": "Agent Job",
    "title": null,
    "prompt": null,
    "status": "complete",
    "progress": 100,
    "resultUrl": "https://cdn.sangtao.ai/agent-jobs/acff47cb.../fa3c91.png",
    "resultImages": [
      "https://cdn.sangtao.ai/agent-jobs/acff47cb.../fa3c91.png"
    ],
    "resultData": {
      "resultUrl": "https://cdn.sangtao.ai/agent-jobs/acff47cb.../fa3c91.png",
      "imageUrls": [
        "https://cdn.sangtao.ai/agent-jobs/acff47cb.../fa3c91.png"
      ],
      "width": 1024,
      "height": 1024,
      "durationMs": 13100
    },
    "error": null,
    "failureKind": null,
    "hasDownloadableAssets": true,
    "queuePosition": null,
    "etaSeconds": null,
    "etaCompleteSeconds": null,
    "elapsedSeconds": 13.1,
    "creditCost": 0,
    "createdAt": "2026-09-19T09:42:59Z",
    "processingAt": "2026-09-19T09:43:17Z",
    "completedAt": "2026-09-19T09:43:30Z",
    "model": "gpt-image-latest",
    "resolvedModel": "gpt-image-2.6",
    "server": "standard"
  }
}