ToAPIsToAPIs
작업

계정 작업 목록 조회

현재 계정의 영구 저장 작업을 페이지 또는 일괄 조회

GET
/api/v1/tasks

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

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

동작

계정의 영속 작업을 페이지로 반환하여 생성 작업의 상태와 청구를 확인합니다. 기본 범위는 최근 24시간, 최대 31일이며 내부 ID 내림차순입니다. ids 일괄 조회는 페이지네이션 없이 응답의 meta에 from/to가 없습니다.

영속 작업 메타데이터만 반환하며 생성 결과 URL이나 프롬프트는 포함되지 않습니다. 조회는 상류를 폴링하지 않고 정산, 환불, Webhook도 트리거하지 않습니다. 영상 전송이나 정산이 끝나지 않은 동안은 processing이고 finished_at=null입니다.

청구 데이터를 반환하기 전에 확인 가능 여부를 검사하여 통과하지 못하면 신뢰할 수 없는 데이터 대신 503을 반환합니다. 개별 작업의 청구를 확인할 수 없으면 billing=null입니다. billing.status=pending 동안은 금액 필드를 생략하며 확인 후 settled 또는 refunded가 됩니다.

인증

Authorizationstring헤더필수

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

요청 매개변수

fromstring쿼리

시간대가 포함된 RFC 3339 시작 시각. 해당 시각을 포함하며 to 와 함께 지정합니다.

제약: date-time.

tostring쿼리

시간대가 포함된 RFC 3339 종료 시각. 해당 시각을 제외하며 from 보다 늦어야 합니다.

제약: date-time.

modelstring쿼리

모델 식별자 정확히 일치.

제약: maxLength=191.

cursorstring쿼리

이전 next_cursor 를 그대로 전달하고 필터를 유지합니다. 조건을 변경하면 처음부터 조회합니다.

제약: maxLength=2048.

limitinteger쿼리기본값: 20

페이지당 최대 항목 수.

제약: minimum=1; maximum=50; 기본값: 20.

typestring쿼리

작업 유형. status 쿼리는 지원하지 않습니다.

제약: image, video, music, other.

client_business_idstring쿼리

업무 ID 정확히 일치. 앞뒤 공백과 제어 문자는 허용하지 않습니다.

제약: minLength=1; maxLength=191.

idsstring쿼리

쉼표로 구분한 플랫폼 작업 ID. 중복 포함 최대 20 개이며 모든 다른 쿼리와 함께 사용할 수 없습니다. 중복을 제거한 최초 순서로 반환하고, 없거나 타인의 작업은 생략합니다.

요청 예제

요청 예시

curl --request GET \
  --url 'https://api.toapis.com/api/v1/tasks?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&type=video&limit=20' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'
import requests

response = requests.get(
    "https://api.toapis.com/api/v1/tasks",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    params={
        "from": "2026-11-01T00:00:00Z",
        "to": "2026-11-02T00:00:00Z",
        "type": "video",
        "limit": "20"
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())
const url = new URL("https://api.toapis.com/api/v1/tasks");
url.search = new URLSearchParams({
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-11-02T00:00:00Z",
  "type": "video",
  "limit": "20"
}).toString();

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" 을 가정합니다. 실제 환산에는 응답 값을 사용하세요.

결과는 data.items 에 있습니다. has_more 와 next_cursor 로 페이지를 조회합니다. 마지막 커서는 null 이며 총 개수는 반환하지 않습니다.

codeinteger

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

messagestring

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

dataobject

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

data.itemsobject[]

현재 페이지의 기록 목록이며 빈 결과는 [] 입니다.

data.items[].idstring

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

data.items[].client_business_idstring | null

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

data.items[].api_key_idstring | null

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

data.items[].typestring

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

data.items[].modelstring

모델 식별자입니다.

data.items[].statusstring

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

data.items[].progressinteger

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

data.items[].created_atstring | null

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

data.items[].finished_atstring | null

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

data.items[].billingobject | null

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

data.items[].billing.statusstring

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

data.items[].billing.creditsstring

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

data.items[].billing.cost_usdstring

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

data.has_moreboolean

다음 페이지가 있는지 나타냅니다.

data.next_cursorstring | null

동일한 필터로 cursor 에 그대로 전달합니다. 마지막 페이지는 null 입니다.

data.metaobject

데이터 출처, 조회 범위 및 집계 기준 등의 메타데이터입니다.

data.meta.scopestring

조회 데이터의 소유 범위이며 인증된 계정 자신입니다.

data.meta.sourcestring

데이터 출처입니다. 로컬 설정이나 원장 스냅샷은 실시간 Stripe 상태를 뜻하지 않습니다.

data.meta.consistencystring

eventual 은 최종 일관성으로 기록이 나중에 갱신될 수 있습니다.

data.meta.fromstring

조회 시간 범위의 시작 시각을 포함합니다.

data.meta.tostring

조회 시간 범위의 종료 시각은 제외합니다.

응답 예제

응답 예시

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "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"
        }
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "meta": {
      "scope": "self",
      "source": "persisted_tasks",
      "consistency": "eventual",
      "from": "2026-11-01T00:00:00Z",
      "to": "2026-11-02T00:00:00Z"
    }
  }
}