> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance에서 invalid image format 오류가 발생하지만 브라우저에서는 링크가 열리는 경우

> Seedance 이미지 링크가 브라우저에서는 정상적으로 열리지만, 작업 제출 시 400 invalid image format이 반환됩니다. 해당 링크는 서버 측 가져오기가 아닌 브라우저에서의 일회성 다운로드용으로 생성되어 Range 요청을 거부하거나, 다운로드 횟수를 제한하거나, 너무 일찍 만료될 수 있습니다. 이 페이지에서는 링크를 점검하는 방법과 공개 URL, 에셋 ID, Base64 중 적절한 방식을 선택하는 방법을 안내합니다.

## 간단한 답변

제공업체가 수신한 것은 이미지가 아니라 사용자의 서버에서 반환된 오류 응답입니다. 브라우저에서 열리는 링크는 **단일 브라우저에서의 다운로드**가 작동한다는 점만을 증명할 뿐입니다. **제공업체의 서버가 이를 가져올 수 있음**을 증명하지는 않습니다.

일반적인 오류는 제출 시 400으로 반환되며, 작업이 생성되지 않습니다:

```text theme={null}
The parameter `content[1]` specified in the request is not valid:
invalid image format (detected format); received: "".
```

`received: ""`은(는) 제공업체가 다운로드한 데이터에서 어떠한 이미지 형식도 감지하지 못했음을 의미합니다.

**가장 간단한 해결 방법**: 일반 오브젝트 스토리지 버킷이나 CDN에 이미지를 호스팅하고 `https://cdn.example.com/xxx.png`와 같은 일반 공개 URL을 전달하십시오.

## 실제 사례

한 고객의 첫 프레임 이미지 링크는 다음과 같았습니다:

```text theme={null}
https://<customer-domain>/api/v1/resource-download-grants/<file-id>/content?access_token=<signed token with an expiry>
```

브라우저에서는 이미지가 정상적으로 표시되었지만, Seedance 작업을 제출하자 위의 400 오류가 반환되었습니다. 해당 링크를 테스트해 보았습니다:

| 테스트                                | 결과                         |
| ---------------------------------- | -------------------------- |
| 일반 GET(브라우저와 동일)                   | 200, PNG 이미지 반환            |
| 파일의 첫 부분을 요청하는 `Range` 헤더를 포함한 GET | **416**, 이미지 대신 JSON 오류 반환 |
| 연속으로 약 10회 다운로드한 후                 | **429**, 다운로드 권한 소진        |
| 동일한 이미지를 Base64로 제출                | **성공**, 동영상 생성됨            |

마지막 행을 통해 이미지와 요청 파라미터에는 문제가 없었음을 알 수 있습니다. 오직 링크에만 문제가 있었습니다.

## 이러한 링크가 존재하는 이유

이것은 이미지 주소가 아닙니다. 이는 **애플리케이션 엔드포인트**입니다. 비공개 사용자 파일은 백엔드에 저장되며, 파일이 필요할 때마다 애플리케이션은 만료 시간, 서명 및 다운로드 횟수 제한이 포함된 임시 다운로드 권한을 발급합니다. 이는 비공개 파일을 보호하는 일반적인 방식입니다. 링크가 유출되더라도 얼마 지나지 않거나 몇 번 사용된 후에는 작동을 멈추며, 모든 다운로드 내역을 감사할 수 있습니다.

이 설계는 **브라우저에서 한 사용자가 한 번 다운로드하는 상황**을 가정한 것입니다. 대신 서버가 파일을 가져오게 되면 문제가 발생합니다:

* **Range 미지원**: 많은 서비스가 포맷을 감지하기 위해 `Range` 헤더로 시작 바이트를 먼저 요청하거나 청크 단위로 다운로드하여 미디어를 가져옵니다. 이러한 엔드포인트는 전체 파일만 반환하며 Range 요청에는 오류로 응답합니다
* **다운로드 횟수 제한**: 제공자가 미디어를 가져올 때 사전 확인(probe)을 수행하고, 다운로드하며, 실패 시 재시도할 수 있으므로 반드시 한 번만 다운로드한다고 볼 수 없습니다. 제한 횟수를 모두 소진하면 응답으로 오류 JSON이 반환됩니다
* **짧은 만료 시간**: 링크가 만료되면 반환되는 응답 또한 이미지가 아닙니다

오브젝트 스토리지나 CDN(R2, S3, OSS, TOS 등)의 공개 URL에는 이러한 제한이 전혀 없습니다. 정적 파일을 직접 가리키며, Range를 지원하고, 다운로드 횟수 제한이 없으며, 추가 헤더나 쿠키도 필요하지 않습니다.

## 이미지 전달 방식 선택

| 방식                                     | 사용 시기                                  | 참고 사항                                                                                                                                                |
| -------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| **공개 URL** (권장)                        | 한 번만 사용하는 이미지                          | 요청 본문 크기가 매우 작습니다. 제공업체의 서버에서 파일을 직접 가져오며, 용량과 대역폭이 훨씬 넉넉합니다. 링크는 아래의 검사를 통과해야 합니다                                                                   |
| **에셋 ID** `asset://...`                | 동일한 이미지를 반복해서 참조하거나 사실적인 사람 얼굴이 포함된 경우 | 한 번 업로드한 후 매번 짧은 문자열만 전달하면 됩니다. [에셋 우선 워크플로](/ko/api-capabilities/seedance2/asset-first-workflow)를 참고하십시오                                            |
| **Base64** `data:image/png;base64,...` | 적절한 공개 URL을 사용할 수 없을 때의 대체 수단          | 인코딩 시 크기가 약 3분의 1 정도 증가하며, 모든 데이터가 로컬 머신에서 업로드되므로 제출 속도가 눈에 띄게 느려집니다. 한 테스트에서는 2.3 MB PNG 파일이 3.1 MB 요청 본문이 되었고, create-task 호출이 반환되는 데 약 60초가 걸렸습니다 |

파일이 이러한 유형의 다운로드 권한 부여 엔드포인트 뒤에 있는 경우, 제출하기 전에 다른 링크를 생성하십시오:

* 파일이 이미 오브젝트 스토리지(OSS, S3, R2 등)에 있다면, 스토리지 서비스에서 **사전 서명된 URL**을 생성하고 만료 시간을 최소 1시간 이상으로 설정하십시오. 사전 서명된 URL은 시간에 의해서만 만료되고, 다운로드 수 제한이 없으며, Range를 지원합니다
* 그렇지 않은 경우, 이미지를 공개 오브젝트 스토리지 버킷이나 CDN으로 복사한 후 Seedance에 새 URL을 전달하십시오

## 제출 전 링크 확인하기

인터넷 접속이 가능한 모든 머신에서 다음 두 명령어를 실행하십시오. `<URL>`을(를) 이미지 링크로 교체하고, 셸이 `&`을(를) 해석하지 않도록 작은따옴표로 감싼 상태를 유지하십시오:

```bash theme={null}
# 1. Plain download: expect 200 and an image Content-Type such as image/png or image/jpeg
curl -s -o /dev/null -w 'code=%{http_code} type=%{content_type} size=%{size_download}\n' '<URL>'

# 2. Range download: expect 206 (or 200 with the full image), never a 4xx
curl -s -o /dev/null -w 'code=%{http_code} type=%{content_type}\n' -H 'Range: bytes=0-1023' '<URL>'
```

다음 사항도 확인하십시오:

* 두 명령어 모두 JSON이나 HTML이 아닌 이미지를 반환하는지
* 다운로드 횟수 제한 없이 반복 다운로드가 계속 정상 작동하는지
* 쿠키, 로그인 세션 또는 추가 헤더가 필요하지 않은지
* 적어도 제출이 완료될 때까지, 이상적으로는 1시간 이상 링크가 유효하게 유지되는지
* 인트라넷 내부나 IP 허용 목록 뒤에 있지 않고 퍼블릭 인터넷에서 링크에 접근할 수 있는지

<Warning>
  다운로드 횟수 제한이 있는 링크를 확인하는 과정에서도 다운로드 횟수가 소진됩니다. 제출하려는 링크를 모두 소진하지 않도록 별도로 발급된 링크로 테스트하십시오.
</Warning>

## 관련 문서

<CardGroup cols={2}>
  <Card title="동영상 생성 API" icon="video" href="/ko/api-capabilities/seedance2/video-generation">
    이미지를 전달하는 세 가지 방법 및 모든 요청 파라미터
  </Card>

  <Card title="에셋 우선 워크플로" icon="gauge" href="/ko/api-capabilities/seedance2/asset-first-workflow">
    세 가지 방식의 제출 시점 비교 및 에셋 업로드 방법
  </Card>
</CardGroup>