가이드

빠른 시작

비동기 Task를 만들고 폴링, 완료, 실패, 콜백을 처리합니다.

RunAPI는 비동기 이미지, 비디오, 오디오, 음악 생성을 위해 Task를 사용합니다. 생성 요청은 빠르게 반환되며, 애플리케이션은 이후 Task를 폴링하거나 해당 엔드포인트의 API 참조에 나열된 콜백 이벤트를 수신합니다.

Task 만들기

Catalog에서 모델과 엔드포인트를 선택한 후 엔드포인트에 필요한 입력을 전송합니다. 이 예시는 Flux 2 텍스트-이미지 Task를 시작합니다:

SHELL

curl -X POST "https://runapi.ai/api/v1/flux_2/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 8c8ba3c9-0ce0-4bbd-a9a7-bf59ab639286" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-text-to-image",
    "prompt": "A product photograph on a clean studio background"
  }'

수락된 비동기 요청은 Task 식별자와 함께 202 Accepted를 반환합니다:

JSON

{
  "id": "task_id",
  "status": "processing"
}

id를 애플리케이션 레코드에 저장하세요. 폴링, 지원, 콜백 조정에 사용되는 안정적인 식별자입니다.

중복 태스크 생성 방지

작업 생성 엔드포인트는 최대 512자의 불투명한 값을 가진 선택적 Idempotency-Key 헤더를 허용합니다. 각 논리적 Task마다 하나의 값을 생성하고, 수락 여부를 확인할 때까지 해당 요청과 함께 보관하세요.

타임아웃 또는 연결 실패로 인해 결과를 알 수 없는 경우, 동일한 키로 동일한 Task 생성 요청을 다시 시도하세요. RunAPI는 두 번째 Task를 생성하고 요금을 청구하는 대신 원래 Task를 반환합니다. 다른 Task 생성 요청에 키를 재사용하면 409 Conflict가 반환됩니다. 의도적으로 새 Task를 위한 새 키를 생성하고, 이 키로 X-Client-Request-Id를 사용하지 마세요.

중단된 동기 요청 복구

느린 동기 엔드포인트는 일반적으로 연결을 열어 두고 이전과 동일한 최종 응답을 반환합니다. 기존 통합에서는 폴링 변경이 필요하지 않습니다.

의도적으로 더 짧은 연결 예산을 위해 Prefer: wait=N을 전송하세요. 해당 명시적 예산 이후에도 Task가 여전히 실행 중이면 RunAPI는 동일한 Task id, 복구를 위한 불투명한 Location URL, 권장 쿼리 지연을 위한 Retry-After와 함께 202 Accepted를 반환합니다. 결과 URL을 직접 구성하지 말고 Location을 그대로 따르세요. 완료된 Task 결과는 종료 HTTP 상태, 허용된 헤더, 콘텐츠 타입, 본문을 보존합니다. response.content_type에 따라 response.body를 디코딩하세요(항상 JSON은 아닙니다).

태스크 폴링

동일한 엔드포인트 경로에 Task 식별자를 추가합니다:

SHELL

curl "https://runapi.ai/api/v1/flux_2/text_to_image/task_id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

status가 processing인 동안 계속 진행합니다. 연속 폴링 대신 요청 간 제한된 백오프를 사용하십시오. Task의 상태가 completed 또는 failed이면 터미널 상태가 됩니다.

완성 처리

completed 응답에는 Task id, 종료 status, 그리고 엔드포인트별 결과 필드가 포함됩니다. 필요한 결과를 저장하고 폴링을 중단하십시오. 모든 미디어 엔드포인트가 동일한 필드를 반환한다고 가정하지 말고, 정확한 결과 형태는 해당 엔드포인트의 API 참조를 확인하십시오.

실패 처리

failed 응답에는 Task id, 종료 status, 그리고 가능한 경우 RunAPI가 작성한 error가 포함됩니다. 폴링을 중단하고 식별자와 오류를 기록하십시오. 애플리케이션에서 해당 실패를 일시적인 오류로 분류한 경우에만 재시도하십시오. 재시도 시 새로운 Task 식별자가 생성됩니다.

콜백 수신

RunAPI가 해당 엔드포인트에 대해 문서화된 콜백 이벤트를 전송하도록 하려면 생성 요청에 공개 HTTPS callback_url을 추가합니다:

JSON

{
  "model": "flux-2-pro-text-to-image",
  "prompt": "A product photograph on a clean studio background",
  "callback_url": "https://your-domain.com/webhooks/runapi"
}

각 콜백 본문은 엔드포인트의 API 레퍼런스에 있는 하나의 라이프사이클 이벤트와 일치하며, 폴링 전용 청구 세부 정보는 포함하지 않습니다. 종료 콜백은 종료 폴링 응답과 동일한 결과 필드를 포함하며, 일부 엔드포인트는 문서화된 processing 콜백도 전송합니다. 성공적인 HTTP 응답을 신속하게 반환하고, 전달이 지연되거나 콜백 핸들러를 사용할 수 없을 때 조정을 위한 폴링을 유지하세요.

콜백 시크릿 생성, 서명 검증 및 안전한 재시도 처리 방법은 콜백을 참조하세요.