비동기 작업 Webhook

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

비동기 이미지와 비디오 작업에 generation.completed, generation.failed를 전송하고 테스트는 endpoint.test입니다. 최소 1회 전달이므로 동일 event ID를 멱등 처리하세요. Token 편집에서 HTTPS 기본 URL, 한 번만 표시되는 32-byte secret, 활성화와 테스트를 설정합니다. callback_url이 없으면 기본 URL을 사용하며, 지정 시 같은 scheme/host/port의 path/query만 변경할 수 있습니다. 미설정 시 400 webhook_not_configured입니다.

{"id":"evt_xxx","type":"generation.completed","api_version":"v1","created_at":1783953302,"data":{"task_id":"tsk_xxx","client_business_id":"order_123","task_type":"image","model":"model-name","status":"SUCCESS","progress":"100%","result":{"type":"image","data":[{"url":"https://cdn.example/result.png"}]},"usage":{"charge_type":"per_request","requests":1},"billing":{"status":"settled","credits":"100","cost_usd":"0.5"},"error":null,"created_at":1783953000,"finished_at":1783953300,"completed_at":1783953300,"expires_at":1784039700}}

최종 실패는 내부 재시도와 환불 또는 과금 확정이 끝난 뒤에만 전송됩니다. 식별자 의미와 처리 방법은 오류 코드 빠른 참조 를 확인하세요. Webhook 의 data.error 는 일부 작업 조회의 reason 필드를 보장하지 않습니다.

{"id":"evt_failure","type":"generation.failed","api_version":"v1","created_at":1783953302,"data":{"task_id":"tsk_failure","client_business_id":"order_456","task_type":"video","model":"model-name","status":"FAILURE","progress":"100%","result":null,"billing":{"status":"refunded","credits":"0","cost_usd":"0"},"error":{"code":"generation_failed","message":"Generation failed after retries"},"created_at":1783953000,"finished_at":1783953300}}

{"id":"evt_test","type":"endpoint.test","api_version":"v1","created_at":1783953302,"data":{"task_id":"endpoint_test","task_type":"image","status":"SUCCESS","progress":"100%","result":{"message":"ToAPIs webhook endpoint test"},"error":null,"created_at":0}}

task_type: image|video. 결과는 공개 작업 조회 형식과 같으며 channel ID, upstream task ID/key, credential, PrivateData는 포함하지 않습니다.

사용량, 과금 및 작업 조회의 차이

이미지와 동영상 성공 이벤트는 data.usage를 포함할 수 있습니다. 과금 수량, 확인 가능한 모델 토큰 내역, 도구 사용 횟수의 정의는 작업 조회와 같습니다. 작업 사용량 필드를 참고하세요. 동영상 이벤트는 data.generation도 포함할 수 있습니다. Seedance 메타데이터와 호환 사용량은 동영상 작업 조회를 참고하세요. data.billing은 status, credits, cost_usd를 포함할 수 있습니다. 금액은 십진수 문자열이며 pending이면 생략합니다. refunded는 순 청구 금액이 0으로 확인되었음을 뜻합니다. 확인할 수 없는 객체는 생략하지만 무료라는 의미는 아닙니다. Webhook과 작업 조회는 같은 확인 조건을 사용합니다. 제출 시 한 번에 과금되는 고정 과금 작업을 포함해 과금이 확인되면 둘 다 settled와 실제 금액을 반환합니다. data.usage에 charge_type 등 과금 수량이 있으면 data.billing도 항상 settled입니다.

`data.billing` 필드 값

필드	타입	값
`status`	string	`pending`: 정산 또는 환불이 아직 확인되지 않았으며 금액을 생략합니다. `settled`: 최종 청구 금액이 확정되어 실제 금액을 반환하며, 무료 작업은 `"0"`입니다. `refunded`: 환불되었거나 실패 후 순 청구 금액이 없는 것으로 확인되었으며 두 금액 모두 `"0"`입니다
`credits`	string	실제로 청구된 ToAPIs 크레딧을 `"100"`과 같은 십진수 문자열로 반환합니다. `settled`와 `refunded`일 때만 반환합니다
`cost_usd`	string	같은 청구의 USD 금액을 `"0.5"`와 같은 십진수 문자열로 반환합니다. `credits`와 같은 조건에서 반환하며 할인과 배율을 포함하고 공급자 원가가 아닙니다

성공 이벤트는 settled이며, 정산에서 선차감 금액을 전부 돌려준 경우에는 refunded입니다. 실패 이벤트는 환불이 완료된 뒤 전송되며 refunded입니다. 금액을 확인할 수 없으면 data.billing 객체 전체를 생략합니다.

`data.usage` 필드 값

필드	타입	값
`charge_type`	string	과금 방식: `per_request`, `per_second`, `per_token`
`requests`	integer	과금 요청 횟수. `per_request`일 때 반환합니다. 이미지 요청의 `n`을 직접 곱하지 않습니다
`billed_tokens`	integer	가격 계산에 사용한 토큰 수. `per_token`일 때 반환합니다
`output_seconds`	integer	과금 대상 출력 동영상 길이, 정수 초 단위. `per_second`일 때 반환합니다
`input_seconds`	integer	과금 대상 입력 동영상 길이, 정수 초 단위. 0이면 생략합니다
`input_images`	integer	무료 한도를 제외하고 과금 대상이 된 입력 이미지 수. 0이면 생략합니다
`input_tokens`, `output_tokens`, `total_tokens`	integer	모델이 보고한 입력, 출력, 전체 토큰 수
`input_tokens_details`	object	이미지 입력 세부 내역: `text_tokens`, `image_tokens`, `cached_tokens`, `cached_tokens_details.text_tokens`, `cached_tokens_details.image_tokens`. 캐시된 토큰은 전체 입력 토큰 수에 이미 포함됩니다
`output_tokens_details`	object	이미지 출력 세부 내역: `text_tokens`, `image_tokens`. 텍스트와 사고 과정의 가격이 같아 구분하지 않은 경우 `text_or_reasoning_tokens`가 추가되며 `text_tokens`에 포함하지 않습니다
`prompt_tokens`, `completion_tokens`	integer	동영상 모델이 보고한 토큰 수
`tool_usage`	object	도구 사용 횟수: `web_search`, `image_search`, `grounding_queries`. 사용한 경우에만 반환합니다

charge_type부터 input_images까지는 과금 수량이며 data.billing.status=settled와 함께만 반환합니다. 토큰 내역과 도구 사용 횟수는 업스트림 모델이 제공한 대로 독립적으로 반환합니다. 반환하지 않는 필드는 0으로 채우지 않고 생략합니다. Webhook은 이벤트 생성 시점의 스냅샷이며 작업 조회는 가장 최근에 확인된 상태를 읽습니다. 누락된 사용량이나 금액을 기다리지 않고 전달하며 재시도 규칙도 바꾸지 않습니다. 생성된 이벤트를 나중에 보완하지 않고 재시도 시 원래 이벤트 본문을 사용합니다. 이벤트 구조와 api_version: "v1"은 유지됩니다. Webhook은 data.task_id, SUCCESS / FAILURE, 문자열 진행률 "100%"를 사용합니다. 작업 조회는 id, 소문자 상태, 정수 진행률을 사용합니다. 시간 필드는 공개 generation.task 조회와 이름과 의미가 같으며 모두 Unix 초입니다. data.created_at은 작업 제출 시각, data.finished_at은 종료 시각이며, 성공 시 data.completed_at과 data.expires_at(결과 만료 시각, 종료 시각 + 24시간)도 반환합니다. 값이 없는 필드는 생략합니다. 기존 data.submitted_at은 data.created_at으로 대체되어 더 이상 반환되지 않습니다. 이벤트 최상위 created_at은 이벤트 생성 시각이며 작업 제출 시각이 아닙니다. 접근 정책에 따라 두 응답의 미디어 URL은 다를 수 있습니다.

Seedance 동영상 성공 이벤트 예시

예시는 필드 구조를 보여 주며 모델의 현재 가격이나 고정 과금 방식을 나타내지 않습니다. 실제 작업에서 반환된 필드와 금액을 확인하세요. Seedance 성공 이벤트의 data.result.data[]에도 fallback_url과 fallback_last_frame_url이 포함될 수 있습니다. url과 last_frame_url을 우선 사용하고 원본 URL에 접근할 수 없을 때만 해당 대체 URL을 사용하세요. 대체 필드 생략은 작업 실패를 의미하지 않습니다. 이벤트는 생성 시점의 URL을 유지하며 이후 사본이 변경되어도 기존 이벤트나 재시도 페이로드를 수정하지 않습니다. 필드 정의와 사용 방법은동영상 작업 조회를 참고하세요.

{
  "id": "evt_seedance_example",
  "type": "generation.completed",
  "api_version": "v1",
  "created_at": 1792400061,
  "data": {
    "task_id": "task_seedance_example",
    "client_business_id": "order_123",
    "task_type": "video",
    "model": "seedance-2-global",
    "status": "SUCCESS",
    "progress": "100%",
    "result": {
      "type": "video",
      "data": [
        {
          "url": "https://cdn.example/result.mp4",
          "fallback_url": "https://files.toapis.com/videos/task_seedance_example/result.mp4",
          "format": "mp4",
          "last_frame_url": "https://cdn.example/last-frame.jpg",
          "fallback_last_frame_url": "https://files.toapis.com/videos/task_seedance_example/last-frame.jpg"
        }
      ]
    },
    "usage": {
      "charge_type": "per_token",
      "billed_tokens": 87300,
      "completion_tokens": 87300,
      "total_tokens": 87300
    },
    "billing": {
      "status": "settled",
      "credits": "87.3",
      "cost_usd": "0.4365"
    },
    "generation": {
      "duration": 5,
      "resolution": "720p",
      "ratio": "16:9",
      "generate_audio": true,
      "usage": {
        "completion_tokens": 87300,
        "total_tokens": 87300
      }
    },
    "error": null,
    "created_at": 1792400000,
    "finished_at": 1792400060,
    "completed_at": 1792400060,
    "expires_at": 1792486460
  }
}

User-Agent: ToAPIs-Webhook/1.0
X-ToAPIs-Webhook-Id
X-ToAPIs-Webhook-Timestamp
X-ToAPIs-Webhook-Signature: v1=<current>[,v1=<previous>]

서명 원문은 event_id + "." + timestamp + "." + raw_request_body, 알고리즘은 HMAC-SHA256입니다. 최초 요청은 5분 초과 timestamp를 거부하고 secret 회전 후 24시간은 신/구 서명을 모두 허용합니다.

Python

def verify(headers, raw_body, secrets):
    event_id=headers["X-ToAPIs-Webhook-Id"]; timestamp=int(headers["X-ToAPIs-Webhook-Timestamp"])
    if abs(int(time.time())-timestamp)>300: return False
    signed=f"{event_id}.{timestamp}.".encode()+raw_body
    received=[v.strip()[3:] for v in headers["X-ToAPIs-Webhook-Signature"].split(",") if v.strip().startswith("v1=")]
    return any(hmac.compare_digest(hmac.new(s.encode(),signed,hashlib.sha256).hexdigest(),r) for s in secrets for r in received)

Node.js

function verify(headers,rawBody,secrets){const id=headers['x-toapis-webhook-id'];const ts=Number(headers['x-toapis-webhook-timestamp']);if(!Number.isFinite(ts)||Math.abs(Date.now()/1000-ts)>300)return false;const signed=Buffer.concat([Buffer.from(`${id}.${ts}.`),rawBody]);const received=headers['x-toapis-webhook-signature'].split(',').filter(v=>v.trim().startsWith('v1=')).map(v=>v.trim().slice(3));return secrets.some(secret=>received.some(sig=>{const expected=crypto.createHmac('sha256',secret).update(signed).digest('hex');return expected.length===sig.length&&crypto.timingSafeEqual(Buffer.from(expected),Buffer.from(sig));}));}

func Verify(id,ts,sig string,body []byte,secrets []string) bool { unix,err:=strconv.ParseInt(ts,10,64);now:=time.Now().Unix();if err!=nil||now-unix>300||unix-now>300{return false};signed:=append([]byte(id+"."+ts+"."),body...);for _,secret:=range secrets{mac:=hmac.New(sha256.New,[]byte(secret));mac.Write(signed);expected:=hex.EncodeToString(mac.Sum(nil));for _,v:=range strings.Split(sig,","){if hmac.Equal([]byte(expected),[]byte(strings.TrimPrefix(strings.TrimSpace(v),"v1="))){return true}}};return false }

첫 전달은 즉시 수행하며 실패 후 10초, 30초, 2분, 10분, 1시간, 6시간, 24시간에 재시도합니다. 2xx만 성공이고 3xx는 따라가지 않으며 4xx/5xx는 재시도합니다. timeout은 10초입니다. 매 전달마다 HTTPS, userinfo, fragment, 잘못된 port, SSRF, DNS/IP와 DNS rebinding을 검증합니다. 실패 시 상태 조회를 대체 경로로 사용하고 만료 가능한 결과 URL을 즉시 저장하세요. 실명 인증, 결제, OAuth callback은 제외됩니다. 속도 제한.

개요

빠른 시작

모델 카탈로그

채팅 API

이미지 API

비디오 API

음악 API

작업 관리

파일 업로드

계정

자주 묻는 질문

사용량, 과금 및 작업 조회의 차이

`data.billing` 필드 값

`data.usage` 필드 값

Seedance 동영상 성공 이벤트 예시

​사용량, 과금 및 작업 조회의 차이

​data.billing 필드 값

​data.usage 필드 값

​Seedance 동영상 성공 이벤트 예시

사용량, 과금 및 작업 조회의 차이

`data.billing` 필드 값

`data.usage` 필드 값

Seedance 동영상 성공 이벤트 예시