플랫폼 헤더 — 추론 동작을 제어하는 HTTP 헤더

fal에서 모델이나 자신이 배포한 앱을 호출할 때, HTTP 헤더로 요청이 처리되는 방식을 인프라 레벨에서 제어할 수 있어요. 이 헤더들은 모델 입력 인자(prompt, image_size 등)나 SDK 메서드 파라미터(start_timeout, client_timeout 등)와는 별개예요. 재시도·페이로드 저장·미디어 만료·라우팅을 다루고, 일부는 SDK 파라미터가 자동으로 대응 헤더를 설정하기도 해요 — 예컨대 SDK에서 start_timeout=30을 주면 내부적으로 X-Fal-Request-Timeout: 30이 설정돼요. 반면 X-Fal-Store-IO 같은 헤더는 headers 딕셔너리로만 지정할 수 있어요.

출처: fal.ai Platform Headers

`X-Fal-Request-Timeout` (start_timeout)

서버 측 시작까지의 데드라인(초)이에요. 이름과 달리 총 요청 시간을 제한하지 않아요. 요청을 제출한 시점부터 카운트가 시작돼 큐 대기·러너 확보·실패한 재시도 시도까지를 포함하고, 러너가 처리를 성공적으로 시작하면 타이머가 멈춰서 추론 자체는 필요한 만큼 오래 돌 수 있어요. 데드라인 전에 어떤 러너도 처리를 시작하지 못하면 서버가 504 Gateway Timeout을 X-Fal-Request-Timeout-Type: user와 함께 돌려줘요.


헤더	`X-Fal-Request-Timeout`
기본값	타임아웃 없음
최솟값	> 0.1초
SDK 파라미터	`submit()`·`subscribe()`·`run()`의 `start_timeout`

`X-Fal-Runner-Hint` (hint)

특정 러너로 요청을 보내도록 유도하는 라우팅 힌트예요. 이미 LoRA 어댑터나 컨버세이션 상태를 메모리에 올려 둔 러너에 요청을 고정하는 세션 어피니티에 유용해요. 힌트를 준 러너를 못 쓰면 fal이 다른 러너로 라우팅해요.


헤더	`X-Fal-Runner-Hint`
기본값	자동 라우팅
SDK 파라미터	`submit()`·`subscribe()`·`run()`의 `hint`

`X-Fal-Queue-Priority` (priority)

요청의 큐 우선순위예요. 우선순위는 엔드포인트별 큐에 적용되는데, 같은 엔드포인트로 오는 모든 요청은 누가 보냈든 하나의 큐를 공유해요. 즉 공유 모델 API에서 "low"를 설정하면 다른 사용자들의 요청보다 뒤로 밀리는 것이겠죠.


헤더	`X-Fal-Queue-Priority`
기본값	`"normal"`
값	`"normal"`, `"low"`
SDK 파라미터	`submit()`·`subscribe()`의 `priority`

`X-Fal-Object-Lifecycle-Preference`

생성된 파일이 fal의 CDN에 얼마나 오래 저장되는지와 누가 접근할 수 있는지 제어해요. expiration_duration_seconds(데이터 보존)와 initial_acl(파일 접근 제어) 필드를 가지며, 둘 다 선택 사항이에요. SDK로는 headers 딕셔너리에 JSON 문자열을 담아 넘겨요.

import json

result = fal_client.subscribe(
    "fal-ai/nano-banana-2",
    arguments={"prompt": "a sunset"},
    headers={
        "X-Fal-Object-Lifecycle-Preference": json.dumps({
            "expiration_duration_seconds": 3600
        })
    },
)

`X-Fal-Store-IO`

요청·응답 JSON 페이로드의 저장 여부를 꺼요. "0"으로 설정하면 JSON 페이로드의 저장만 막지, 처리 중 생성된 CDN 파일은 미디어 만료 설정에 따라 계속 접근 가능해요.

result = fal_client.subscribe(
    "fal-ai/nano-banana-2",
    arguments={"prompt": "a sunset"},
    headers={"X-Fal-Store-IO": "0"},
)

`X-Fal-No-Retry`

이 요청에 대한 자동 재시도를 꺼요. 기본적으로 큐 기반 요청은 서버 에러(503, 504, 연결 에러)에 대해 총 10회까지 재시도돼요.


헤더	`X-Fal-No-Retry`
기본값	재시도 활성
값	`"1"`, `"true"`, `"yes"`로 비활성화

result = fal_client.subscribe(
    "fal-ai/nano-banana-2",
    arguments={"prompt": "a sunset"},
    headers={"X-Fal-No-Retry": "1"},
)

`X-Fal-Retry-Config`

X-Fal-No-Retry의 전부 아니면 전무(all-or-nothing) 방식 대신, 재시도 조건별로 횟수를 따로 지정해요. 값은 JSON 객체로, 재시도 조건(server_error, timeout, connection_error)마다 retries 개수를 담아요. retries는 첫 시도 이후의 추가 시도 횟수라서 retries: 3이면 해당 조건에 대해 총 4회까지 허용돼요. 이 헤더는 자신의 앱에서만 동작하고 공유·공개 모델 API에서는 무시돼요.


헤더	`X-Fal-Retry-Config`
기본값	조건별 플랫폼 기본 재시도
값	JSON 객체, 예: `{"timeout": {"retries": 0}, "server_error": {"retries": 3}}`

import json

result = fal_client.subscribe(
    "your-username/your-app-name",
    arguments={"prompt": "a sunset"},
    headers={
        "X-Fal-Retry-Config": json.dumps(
            {"timeout": {"retries": 0}, "server_error": {"retries": 3}}
        )
    },
)

`x-app-fal-disable-fallback`

이 요청에 대한 자동 모델 폴백을 꺼요. 기본적으로 fal은 주 엔드포인트를 못 쓰면 동등한 대체 엔드포인트로 요청을 재라우팅할 수 있어요.

result = fal_client.subscribe(
    "fal-ai/nano-banana-2",
    arguments={"prompt": "a sunset"},
    headers={"x-app-fal-disable-fallback": "true"},
)

`fal_max_queue_length`

엔드포인트의 큐에 이보다 많은 요청이 대기 중이면 429로 요청을 거부해요(모든 호출자를 합산). 긴 큐에서 기다리는 것보다 빨리 실패하는 걸 선호하는 지연 민감 애플리케이션에 유용해요. 쿼리 파라미터로 URL에 붙여 전달해요.

curl -X POST "https://queue.fal.run/fal-ai/nano-banana-2?fal_max_queue_length=10" \
  -H "Authorization: Key $FAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a sunset"}'

응답 헤더

fal이 응답에서 돌려주는 헤더들이 있어요. 이건 정보 제공용이라 직접 설정하는 게 아니라요. 주요 응답 헤더로는 요청 식별용 x-fal-request-id, start_timeout 데드라인이 504를 유발했을 때 붙는 X-Fal-Request-Timeout-Type: user, 실패 카테고리(request_timeout, startup_timeout, runner_disconnected 등)를 알려주는 X-Fal-Error-Type, 스티키 세션 라우팅용 x-fal-runner-hints가 있어요. 참고로 모든 응답 헤더 크기 합계는 16KB로 제한되니, 앱이 큰 커스텀 헤더(예: provide_hints()의 상세 라우팅 힌트)를 설정하면 이 제한을 넘지 않도록 주의해야 해요.

플랫폼 헤더 — 추론 동작을 제어하는 HTTP 헤더