ToAPIsToAPIs
작업

계정 작업 상세 조회

작업 ID로 작업 메타데이터와 결제 상태 조회

GET
/api/v1/tasks/{task_id}

중국 본토 사용자 안내: 중국 본토 사용자는 https://api.toapis.cn 를 API 엔드포인트(Base URL)로 사용해 주세요. 본 문서의 예시에서 https://api.toapis.com 을 https://api.toapis.cn 로 바꿔 주세요.

인증, 페이지 처리 및 오류는 시작하기를 참조하세요.

동작

task_id로 작업의 영속 메타데이터와 확인 가능한 청구를 반환하여 생성 작업의 진행과 비용을 추적합니다. 생성 결과, 프롬프트, 재생 데이터는 반환하지 않으며 조회는 작업 상태를 능동 갱신하지 않고 정산 또는 Webhook도 트리거하지 않습니다.

task_id만 사용할 수 있고 client_business_id로의 대체는 없습니다. 타인이거나 존재하지 않는 작업은 404를 반환합니다.

영상 전송이나 정산이 끝나지 않은 동안은 processing이고 finished_at=null입니다. 청구 데이터를 반환하기 전에 확인 가능 여부를 검사하여 통과하지 못하면 신뢰할 수 없는 데이터 대신 503을 반환합니다. 개별 작업의 청구를 확인할 수 없으면 billing=null입니다.

billing.status=pending 동안은 금액 필드를 생략하며 확인 후 settled 또는 refunded가 됩니다.

인증

Authorizationstring헤더필수

Bearer YOUR_SYSTEM_ACCESS_TOKEN 을 사용합니다. 모델 API 키는 사용할 수 없습니다. X-User-Id 는 필요하지 않습니다.

요청 매개변수

task_idstring경로필수

플랫폼 작업 ID. 업무 ID 로 대체할 수 없으며 앞뒤 공백과 제어 문자는 거부합니다.

제약: minLength=1; maxLength=191.

요청 예제

요청 예시

curl --request GET \
  --url 'https://api.toapis.com/api/v1/tasks/task_example_01' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'
import requests

response = requests.get(
    "https://api.toapis.com/api/v1/tasks/task_example_01",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    timeout=30,
)
response.raise_for_status()
print(response.json())
const url = new URL("https://api.toapis.com/api/v1/tasks/task_example_01");

const response = await fetch(url, {
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

응답 필드

예시는 가상 데이터이며 credits_per_usd="100" 을 가정합니다. 실제 환산에는 응답 값을 사용하세요.

codeinteger

결과 코드. 0 은 성공입니다.

messagestring

성공 시 빈 문자열이며 오류 메시지는 현지화됩니다.

dataobject

현재 조회의 결과 객체입니다.

data.idstring

작업 상세 조회에 사용하는 플랫폼 ID 이며 업무 ID 가 아닙니다.

data.client_business_idstring | null

작업 생성 시 저장한 업무 ID 이며 플랫폼 작업 ID 와 다릅니다. 불명확하거나 해당하지 않으면 null 입니다.

data.api_key_idstring | null

연결된 모델 API 키 ID. 연결된 키가 없으면 null 입니다.

data.typestring

작업 유형입니다. 허용 값: image, video, music, other.

data.modelstring

모델 식별자입니다.

data.statusstring

작업의 공개 상태. 동영상 저장이나 정산 중에는 processing 입니다. 허용 값: pending, processing, completed, failed.

data.progressinteger

작업 진행률이며 범위는 0-100 입니다.

data.created_atstring | null

생성 시각입니다. 시간대가 포함된 RFC 3339 형식입니다. 불명확하거나 해당하지 않으면 null 입니다.

data.finished_atstring | null

확인된 작업 종료 시각. 처리 중이거나 미확인 시 null 입니다. 시간대가 포함된 RFC 3339 형식입니다.

data.billingobject | null

확인 가능한 작업 결제 정보이며 미확인 시 null 입니다.

data.billing.statusstring

작업 결제 상태. pending 에서는 금액을 생략하고 확정 시 settled 또는 refunded 입니다. 허용 값: pending, settled, refunded.

data.billing.creditsstring

확인된 작업 결제 credits. pending 에서는 생략합니다. 정밀도를 유지하기 위해 십진수 문자열로 반환합니다.

data.billing.cost_usdstring

확인된 작업 결제 USD 금액. pending 에서는 생략합니다. 정밀도를 유지하기 위해 십진수 문자열로 반환합니다.

응답 예제

응답 예시

{
  "code": 0,
  "message": "",
  "data": {
    "id": "task_example_01",
    "client_business_id": "order_example_01",
    "api_key_id": "42",
    "type": "video",
    "model": "example-video-model",
    "status": "completed",
    "progress": 100,
    "created_at": "2026-11-01T08:00:00Z",
    "finished_at": "2026-11-01T08:01:00Z",
    "billing": {
      "status": "settled",
      "credits": "2",
      "cost_usd": "0.02"
    }
  }
}