가이드

빠른 시작

비동기 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를 애플리케이션 레코드에 저장하세요. 폴링, 지원, 콜백 조정에 사용되는 안정적인 식별자입니다.

미디어 입력 보내기

Media Input Field는 미디어 URL을 담는 요청 필드입니다. 이름이 _url 또는 _urls로 끝나는 최상위 필드(예: image_url, image_urls), video_list 각 항목의 url, kling_elements 각 항목의 element_input_urls, element_input_video_urls, element_input_audio_urls가 해당합니다. callback_url는 전달 엔드포인트이며 Media Input Field가 아닙니다. 각 Media Input Field 값에는 공개 HTTPS URL 또는 data:<mime>;base64,<data> 형식의 data URI를 사용할 수 있으며, data URI 하나당 최대 10 MB입니다. RunAPI는 각 data URI를 1시간 후 만료되는 임시 File Upload로 저장하고 해당 업로드를 Task에 사용합니다. 저장할 수 없는 data URI는 오류 코드 invalid_media_input와 함께 422를 반환합니다.

GPT Image 편집 엔드포인트는 source_image_urls에 HTTPS URL만 허용합니다. 로컬 이미지를 이 엔드포인트로 보내려면 먼저 File Upload를 생성하고 반환된 URL을 전달하세요.

10 MB보다 큰 파일은 먼저 POST /api/v1/files로 File Upload를 생성하고 반환된 URL을 전달하세요. multipart 또는 URL 소스 File Upload는 최대 50 MB 파일을 허용합니다. File Upload URL도 1시간 후 만료되므로, 그 이후에 시작하는 Task에는 새 File Upload를 생성하세요.

SHELL

# For this model, non-PNG/JPEG input may return 409 depending on the selected service.
# If rejected, convert WebP/BMP/TIFF/GIF to PNG/JPEG or select a compatible service.
# Actual MIME determines support, even for a .png URL. Rejection happens before task creation or charging.
# This is not a format limit for every service. Existing Task queries remain available.
curl -X POST "https://runapi.ai/api/v1/seedream/decompose_layers" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedream-5-pro-layer-decomposition","image_url":"https://cdn.runapi.ai/public/samples/image.png"}'

중복 태스크 생성 방지

작업 생성 엔드포인트는 최대 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, 엔드포인트별 결과 필드, 그리고 해당 Task의 float USD 금액인 usage.cost가 포함됩니다. 필요한 결과를 저장하고 폴링을 중단하십시오. 모든 미디어 엔드포인트가 동일한 필드를 반환한다고 가정하지 말고, 정확한 결과 형태는 해당 엔드포인트의 API 참조를 확인하십시오.

생성, processing, failed Task envelope에는 usage가 없습니다.

미디어 기반 최종 정산이 필요한 Task는 최종 청구 금액이 기록될 때까지 processing 상태를 유지합니다. 완료 콜백은 정산이 끝난 후에만 전송되며, 콜백의 usage.cost는 이후 Task 조회에서 반환되는 값과 일치합니다. 정산에 필요한 정보가 누락된 경우 이를 0으로 보고하지 않습니다. 해당 정보를 대조하고 보완하는 동안 Task는 processing 상태를 유지합니다. 청구 금액이 0으로 확인되면 usage.cost: 0이 반환됩니다.

실패 처리

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 레퍼런스에 있는 하나의 라이프사이클 이벤트와 일치합니다. completed 콜백은 completed 폴링 응답과 usage.cost를 공유하며, 생성, processing, failed 콜백은 usage를 생략합니다. 종료 콜백은 종료 폴링 응답과 동일한 결과 필드를 포함하며, 일부 엔드포인트는 문서화된 processing 콜백도 전송합니다. 성공적인 HTTP 응답을 신속하게 반환하고, 전달이 지연되거나 콜백 핸들러를 사용할 수 없을 때 조정을 위한 폴링을 유지하세요.

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

Vidu Q4비디오 생성

POST /api/v1/vidu/image_to_video를model: "vidu-q4-image-to-video"및first_frame_image_url와 함께 사용하세요.POST /api/v1/vidu/reference_to_video를model: "vidu-q4-reference-to-video", 비어 있지 않은prompt및 1~15의 순서인reference_image_urls와 함께 사용하세요. 생성 경로에서GET와/:id를 사용하여 각 작업을 검색합니다. 완료된 작업에는 결과 URL의videos배열이 포함됩니다. 완료 알림을 위해 ‘callback_url‘를 제공할 수도 있습니다.

두 엔드포인트 모두 3에서 16 사이의 정수duration_seconds(기본값 5)와540p,720p,1080p,2k또는4k, 기본값720p의output_resolution를 허용합니다.audio는 JSON 부울이며 기본값은true입니다. 명시적false는 생성된 오디오를 비활성화합니다. 프롬프트는 최대 20,000자까지 허용됩니다. 이미지-비디오 프롬프트는 선택 사항이며 첫 번째 프레임이 종횡비를 결정합니다. 비디오 참조에는16:9,9:16,1:1,4:3또는3:4중aspect_ratio, 기본값16:9및 최대 3개의reference_audio_urls가 허용됩니다.

공개HTTP(S)미디어 URL을 사용하세요. 이미지는 ‘JPG/JPEG’, ‘PNG’ 또는 ‘WEBP’여야 합니다. 첫 번째 프레임 이미지는 50MB 이하여야 합니다. 각 참조 오디오 파일은MP3여야 하며 길이는 3~12초, 50MB 이하여야 합니다.RunAPI는 필드 유형, URL 구성표 및 참조 횟수를 확인합니다. 생성 공급자는 원격 미디어 형식, 크기 및 오디오 지속 시간을 비동기적으로 확인합니다. 잘못된 미디어로 인해 일반적인 실패 및 환불 흐름을 통해 작업이 실패할 수 있습니다.

이미지에서 동영상 요금. 참조 이미지에서 동영상 요금.