생성 요청하고 결과 파일 받기
생성 요청부터 결과 파일 수령까지
생성 요청의 작업 ID로 진행 상태를 조회하고 결과 파일을 받는 순서를 안내하며, 작업 비용 확인과 웹훅 알림, 결과를 다음 요청에 쓰는 방법도 다룹니다.
페이지 목차
시작 위치 선택
영상 생성 요청과 일부 이미지 생성 요청은 응답으로 작업 ID를 돌려줍니다. 이 ID로 생성 작업의 진행 상태를 조회하고, 결과 파일이 준비되면 다운로드합니다. 생성이 성공했는지, 파일을 받을 수 있는지, 비용이 얼마인지는 각각 확인합니다.
작업의 상태 값과 확인 순서는 영상 작업과 이미지 작업에서 같고, 파일을 받는 방법은 결과 종류에 따라 다릅니다. 같은 결과 종류에서는 작업 조회부터 파일 다운로드까지의 순서가 모든 모델에서 같습니다. 결과를 응답 본문으로 받는 모델은 작업 ID를 반환하지 않으므로 이 순서가 필요 없습니다. 어느 모델이 작업 ID를 반환하는지는 이미지와 영상 만들기의 모델별 호출 경로에서 확인합니다.
현재 가진 정보에 맞는 절에서 시작하세요.
| 지금 가진 정보 | 다음 행동 |
|---|---|
| 아직 생성 요청을 보내지 않음 | 시작 전 준비를 확인한 뒤 생성 요청을 한 번 보내고 작업 ID를 저장 |
| 동기 응답으로 결과 URL과 작업 ID를 함께 받음 | 응답의 URL로 이미지 받기. 받지 못했거나 링크가 만료됐다면 같은 작업 ID로 상태 확인 |
| 이미 작업 ID가 있음 | 같은 작업의 상태 확인 → 준비된 파일 받기 → 비용 확인 |
| 웹훅 알림을 받음 | 같은 작업의 상태 확인으로 결과와 파일 상태를 읽음. 웹훅으로 완료 알림 받기 참고 |
| 요청 응답을 받지 못해 ID가 없음 | 같은 생성 요청을 자동으로 다시 보내지 말고 접수 여부 확인 |
| 보관한 결과를 다음 생성 요청에 사용하려 함 | 결과를 다음 요청에 쓰기 |
시작 전 준비
- AI 게이트웨이 API 키
요청에 사용할 AI 게이트웨이 API 키를 준비합니다. 작업 상태를 확인할 때도 작업을 만든 스페이스의 키를 사용합니다.
- 작업 ID를 반환하는 생성 모델
키가 속한 스페이스에서 영상 생성 모델이나 작업 ID를 반환하는 이미지 모델을 사용할 수 있어야 합니다. 에셋에서 이용 가능 여부와 단가를 확인합니다. 이용 조건이 불분명하면 플랫폼에 로그인한 뒤 플랫폼 내 문의 기능을 사용합니다.
- 입력 파일의 참조 값조건부
영상 생성에서 로컬 파일을 입력으로 사용할 때만 필요합니다. 입력할 수 있는 파일 종류(이미지, 영상, 오디오)는 모델마다 다릅니다. 파일을 먼저 업로드하고, 업로드 응답의 참조 값을 모델 가이드가 안내하는 필드에 지정합니다. 텍스트만으로 생성할 때는 필요 없습니다.
- 알림을 받을 HTTPS 주소조건부
웹훅으로 완료 알림을 받을 때만 필요합니다. 상태 확인만으로 결과를 확인한다면 필요 없습니다.
생성 요청 보내기
요청 본문을 작성하고 결과 보관 방식을 정한 뒤 요청을 보냅니다. 요청 주소와 인증 헤더, 응답의 형식은 Video Generations 접수 응답과 Image Generations 응답에서 확인합니다. 아래 요청 본문은 자신의 서버 코드에서 사용할 수 있습니다. 로컬에서 영상 작업을 직접 실행하려면 영상 예제를 사용합니다.
요청 본문 쓰기
다음은 예시 모델 Seedance 2.5에 텍스트만 입력하는 영상 생성 본문입니다. 파일 업로드는 필요 없습니다. 이 본문은 Seedance 2.5 전용입니다. 프롬프트 언어와 사용할 수 있는 필드가 모델과 버전마다 다르므로, 다른 모델이나 버전에는 모델 코드만 바꿔 보내지 말고 사용할 모델의 가이드에 맞춰 본문을 작성하세요.
{
"model": "dreamina-seedance-2.5",
"prompt": "바람에 천천히 흔들리는 초원의 풀을 고정 카메라로 촬영한 영상",
"duration": 5,
"resolution": "480p",
"store_media": false
}위 본문에서 생략한 필드의 기본값과 이미지나 영상에서 시작하는 방법은 모델마다 다릅니다. 사용할 모델의 가이드는 Video Generations의 지원 모델 표에서 찾습니다. 모든 모델에 같은 것과 모델마다 다른 것은 이미지와 영상 만들기의 모델별 호출 경로에서 확인합니다.
이미지 생성 본문은 사용할 모델의 가이드에 있는 요청 예시를 따릅니다. 모델 가이드는 Image Generations의 지원 모델 표에서 찾습니다.
결과 보관 정하기
Video Generations 요청에서는 결과 파일의 보관 방식을 store_media 필드로 지정합니다. 이 필드는 모든 모델에 공통입니다. 보관 방식을 직접 선택하려면 요청에 store_media를 명시하세요. 나중에 받거나 다음 요청에 사용할 결과라면 true를 지정하세요. false를 지정했다면 파일이 준비되는 대로 다운로드하세요. 값별 보관 기간과 생략했을 때의 동작은 결과 보관 선택하기에서 확인합니다.
작업 ID 저장하기
완성한 요청 본문을 보냅니다. 작업 ID는 다음 위치에 있습니다.
| 요청 | 보낼 곳 | 작업 ID |
|---|---|---|
| 영상 생성 | POST /v1/video/generations | 응답의 id |
| 이미지 생성, 동기 호출 | POST /v1/images/generations | 응답의 id |
| 이미지 생성, 비동기 호출 | 같은 주소에 Prefer: respond-async 헤더를 추가 | 응답의 id |
요청 주소의 기본 URL은 https://gw.letsur.ai입니다. 영상 생성 요청의 작업 ID는 모델과 관계없이 응답의 id에 있습니다. 이미지 생성을 동기로 호출하면 생성이 끝난 뒤 응답을 받고, 결과 URL은 같은 응답의 data[].url에 있습니다. 비동기로 호출하면 결과를 기다리지 않고 응답을 받습니다. 이때 응답 헤더 Preference-Applied: respond-async로 비동기 접수를 확인합니다. 이 헤더가 없으면 요청이 동기로 처리된 것이므로 응답 본문에서 결과를 확인합니다.
받은 작업 ID를 저장해 두세요. 예를 들어 {"id": "lst-example-job-id", "estimated_cost": null}을 받았다면 이후에는 lst-example-job-id로 같은 작업을 조회합니다. 영상 생성과 비동기 이미지 생성의 HTTP 200 접수 응답은 생성이 끝났다는 뜻이 아닙니다.
생성 요청에는 비용이 발생할 수 있습니다. 같은 요청을 다시 보내면 작업이나 호출이 중복으로 만들어지고 비용도 중복으로 발생할 수 있습니다. 작업 ID를 받았다면 새 생성 요청을 보내기 전에 그 작업부터 조회하세요.
영상 생성 요청에서 작업 ID를 받지 못했다면 플랫폼 내 문의 기능에 스페이스 이름, 요청 시각, 모델 코드와 표시된 오류 코드를 남겨 접수 여부를 확인합니다. 이미지 생성 요청에서 응답을 받지 못했다면 동기 호출의 재시도와 비용 확인에 따라 판단하고, 게이트웨이가 보낸 오류 응답은 Image Generations의 제약과 오류에서 확인합니다.
상태 확인하기
저장한 작업 ID로 GET https://gw.letsur.ai/v1/jobs/{id}를 호출하고 응답의 data.job.status를 확인합니다. 작업을 만든 스페이스의 API 키로 조회합니다. 조회 간격은 모델 가이드에서 확인합니다. 각 상태 값과 필드의 뜻은 Jobs 응답과 상태와 결과 파일에서 확인합니다.
| 상태 | 다음 행동 |
|---|---|
queued, running | 간격을 두고 같은 ID로 다시 조회 |
succeeded | data.job.result.media에서 결과 파일의 준비 상태 확인 |
failed | data.job.error로 실패 원인 확인 후 입력 수정 또는 문의. 이미지 작업의 error.type 값별 대응은 Image Generations의 작업 실패 사유에 있음 |
| HTTP 조회 오류 | 작업 ID, 스페이스와 오류 코드 확인. 새 생성 요청을 자동으로 보내지 않음 |
작업이 succeeded여도 파일 복사가 끝나지 않았을 수 있습니다. 작업의 succeeded와 data.job.result.media[]에 있는 각 파일의 state를 모두 확인하세요.
| 파일 상태 | 다음 행동 |
|---|---|
pending | 기다렸다가 같은 작업을 다시 조회. 이미지 결과는 url: null, url_unavailable_reason: "copying"일 수 있음 |
ready | 영상 결과는 그 항목의 media_id를, 이미지 결과는 그 항목의 url을 확인하고 결과 파일 받기로 이동 |
unavailable | 파일을 받을 수 있는 상태가 아님. url_unavailable_reason이 있으면 이유를 확인하고 필요하면 작업 ID로 문의 |
응답에 Retry-After가 있으면 그 값에 표시된 시간이 지난 뒤 다시 조회합니다.
웹훅으로 완료 알림 받기
작업 ID를 반환하는 모델에 Image Generations 요청을 비동기로 보내면 작업이 끝났을 때 알림을 받을 수 있습니다. 알림을 받아도 결과와 파일 상태는 같은 작업을 조회해 확인합니다. 주소의 조건과 알림 본문의 필드는 Image Generations의 웹훅 알림에 있습니다.
요청 URL의 letsur_webhook 쿼리 파라미터에 알림을 받을 HTTPS 주소를 URL 인코딩해 넣고 요청을 보냅니다. 다음은 예시 모델 Seedream 5.5로 보낸 비동기 요청입니다. https://example.com/hooks/letsur는 예시 주소이므로 알림을 받을 실제 주소로 바꾸세요.
curl "https://gw.letsur.ai/v1/images/generations?letsur_webhook=https%3A%2F%2Fexample.com%2Fhooks%2Fletsur" \
-H "Authorization: Bearer $LETSUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Prefer: respond-async" \
-d '{
"model": "seedream-5.5",
"prompt": "A red apple on a wooden table, soft morning light",
"size": "1K",
"watermark": false
}'알림이 오면 다음 순서로 처리합니다.
- 수신 주소로 오는 POST 알림의
webhook-id헤더 값으로 중복 알림을 걸러 냅니다. 이 값은 작업 ID와 같고, 다시 보낸 알림에도 같은 값이 들어갑니다. - 알림의
type으로 성공과 실패를 구분한 뒤, 같은 작업 ID로 상태를 확인합니다. 알림에는 결과 파일의 정보가 없으므로 같은 작업을 조회해 결과를 읽고 각 파일이ready인지 확인한 뒤 받습니다.
동기 호출에 letsur_webhook을 넣어도 요청은 거절되지 않습니다. 동기 호출의 결과는 응답으로 받으므로 알림을 기다리지 말고 응답으로 결과를 확인하세요. 알림이 오지 않으면 같은 작업의 상태를 확인합니다.
결과 파일 받기
파일을 받는 방법은 결과 종류에 따라 다릅니다. 이미지 결과는 받은 URL로 바로 다운로드하고, 영상 결과는 미디어 ID로 다운로드 링크를 발급받은 뒤 다운로드합니다.
이미지 결과 받기
이미지 결과 파일은 다운로드 링크를 별도로 발급받지 않습니다.
- 동기 호출로 받은 응답에는 결과 URL
data[].url이 들어 있습니다. 이 URL을 받았다고 해서 렛서가 결과 파일 보관을 마친 것은 아니므로, 필요한 이미지는 바로 다운로드해 보관하세요. - 응답의 URL로 받지 못했거나 링크가 만료됐다면 새 생성 요청을 보내지 말고 같은 작업 ID로 상태를 확인합니다. 파일이
ready이면 그 응답의url로 바로 다운로드합니다. - 작업을 조회해 받은 다운로드 URL에는 만료시각
url_expires_at(Unix 초)이 있습니다. 링크가 만료되면 작업을 다시 조회해 새 링크를 받습니다.
링크 유효기간은 파일 보관 기간과 다르므로 필요한 파일은 다운로드해 보관하세요.
영상 결과 받기
- 영상의
media_id로POST https://gw.letsur.ai/v1/media/{media_id}/link를 호출해 다운로드 링크를 발급받습니다. 응답 필드는 Media Links 발급 응답에 있습니다. - 응답의
url을 그대로 쓰고, 리다이렉트를 따라가도록 설정해 파일을 다운로드합니다. 링크에 접근 권한이 들어 있으므로 다운로드 요청에는 AI 게이트웨이 API 키를 넣지 마세요. - 다운로드한 파일의 크기를 보고, 영상을 재생해 제대로 저장됐는지 확인합니다.
- 애플리케이션에서 쓸 영상은 자신의 저장소에 보관하세요. 임시 서명 링크를 장기 재생 주소로 쓰면 링크가 만료된 뒤 영상을 열 수 없습니다.
링크 만료시각은 url_expires_at 필드에, 파일 보관 만료시각은 expires_at 필드에 있습니다. 보관 기간의 기준은 결과 보관 선택하기에 있습니다.
파일을 받지 못했다면 원인에 따라 다음과 같이 대응합니다.
| 상태 | 다음 행동 |
|---|---|
| 파일 준비 중 | Retry-After가 있으면 표시된 시간이 지난 뒤 같은 미디어 ID로 링크 발급 요청 |
| 다운로드 링크 만료 | 파일 보관 기간 안이면 같은 미디어 ID로 새 링크 발급 |
| 파일 보관 만료 | 새 링크로 복구할 수 없음. 이미 받은 사본을 확인하거나 문의 |
| 파일 사본 사용 불가 | 작업 ID와 오류 코드로 문의 |
자세한 오류 응답은 Media Links 발급 요청의 오류에서 확인합니다.
비용 확인하기
비용은 파일 다운로드와 별도로 확인합니다. 작업 비용은 같은 작업 ID로 조회한 응답의 data.job.usage에 나옵니다. 이미지 작업은 동기로 호출해도 응답의 estimated_cost가 null이므로 같은 작업을 조회해 비용을 확인합니다. 파일을 받지 못했거나 비용 필드가 없다고 해서 작업이 무료였거나 자동으로 환불된 것은 아닙니다.
- 영상 작업:
usage가 없을 때의 상태별 대응과 비용 기록 방법은 비동기 영상 작업 비용 확인하기에 있습니다. - 이미지 작업: 비용을 기록할 값과 식별자는 호출 방식별 비용 기록에 있습니다.
usage.items는 참조 이미지와 출력 이미지의 장 수를 세는 항목으로 나뉠 수 있습니다.
필드 구조는 Jobs 사용량과 작업 비용에 있습니다.
결과를 다음 요청에 쓰기
생성한 영상 결과를 다음 영상 생성 요청의 입력으로 사용하려면 앞 작업의 생성 요청에 store_media: true를 지정합니다. 결과 보관 정하기를 참고하세요. 앞 작업의 결과가 준비되면 다음 순서로 참조 값을 준비합니다.
- 앞 작업의 ID로 작업을 조회합니다. 작업이
succeeded이고 사용할 결과 항목의state가ready이면 그 항목의media_id를 저장합니다. 결과가 없거나 사용할 수 없으면 다음 생성 요청을 보내지 않고 앞 작업의 결과를 확인합니다. - 저장한
media_id로 다운로드 링크를 발급받아 파일을 다운로드합니다. 순서는 영상 결과 받기와 같습니다. - 다운로드한 파일을 References로 업로드합니다.
- 업로드 응답의
reference값을 변경하지 않고 다음 요청의 입력 필드에 지정합니다. 값을 지정할 필드는 사용할 모델의 가이드에서 확인합니다.
미디어 ID를 파일 ID로 바꾸거나 URI를 직접 조립하지 마세요. 다음 요청은 앞 작업과 별개인 새 작업이므로 작업 ID와 비용을 앞 작업과 구분해 기록합니다. 새 요청의 응답을 받지 못했다면 생성 요청을 자동으로 다시 보내지 않습니다.
마지막 프레임 반환을 지원하는 모델에서는 앞 영상의 마지막 프레임을 이미지로 받아 다음 장면의 첫 프레임으로 지정할 수 있습니다. 지원하는 모델은 Video Generations의 지원 모델에서, 절차는 마지막 프레임으로 다음 영상 만들기에서 확인합니다.
영상 예제 실행하기
다음 Python 예제로 영상 생성 요청을 보내고, 같은 작업을 조회해 영상 파일을 받습니다.
- Python 3.8 이상
예제는 표준 라이브러리만 쓰므로 추가 패키지를 설치하지 않아도 됩니다.
- AI 게이트웨이 API 키
예제는 서버 환경 변수
LETSUR_API_KEY에서 키를 읽습니다. 변수가 없으면 키를 비밀번호 방식으로 입력받고, 입력한 키를 화면에 표시하지 않습니다. 신뢰할 수 있는 터미널에서 실행하고, 키를 코드나 셸 명령에 직접 넣지 마세요.
예제는 예시 모델 Seedance 2.5의 본문을 보내고 응답의 id를 작업 ID로 저장합니다. 본문에는 앞의 JSON에 없던 aspect_ratio와 generate_audio가 있고, 그중 generate_audio는 일부 모델이 거절하는 필드입니다. 다른 모델에 쓰려면 요청 본문 전체를 그 모델의 가이드에 맞게 바꾸세요.
예제도 앞의 JSON처럼 store_media: false로 임시 보관을 선택합니다. 나중에 받거나 후속 작업에 쓸 결과라면 결과 보관 정하기를 보고 생성 요청의 store_media를 True로 바꾸세요.
아래 전체 코드를 펼쳐 video_job.py로 저장하세요.
video_job.py 전체 코드
import getpass
import json
import os
import sys
from pathlib import Path
from urllib.error import HTTPError
from urllib.parse import quote
from urllib.request import Request, urlopen
BASE = "https://gw.letsur.ai"
RECORD = Path("video-job.json")
key = os.environ.get("LETSUR_API_KEY") or getpass.getpass("AI 게이트웨이 API 키: ")
if not key.strip():
raise SystemExit("API 키가 필요합니다.")
def api(method, path, body=None):
headers = {"Authorization": "Bearer " + key}
data = None
if body is not None:
headers["Content-Type"] = "application/json"
data = json.dumps(body).encode("utf-8")
request = Request(BASE + path, data=data, headers=headers, method=method)
try:
with urlopen(request, timeout=60) as response:
return json.load(response)
except HTTPError as error:
try:
payload = json.load(error)
except (ValueError, OSError):
payload = {}
# source_url 등 민감한 값을 통째로 출력하지 않습니다.
problem = payload.get("error", payload)
code = problem.get("code", problem.get("type", "unknown"))
retry_after = error.headers.get("Retry-After")
if retry_after:
print("다음 조회 또는 링크 요청까지 기다릴 시간:", retry_after)
raise SystemExit(f"HTTP {error.code}, 오류: {code}. 새 생성을 자동 재시도하지 않습니다.")
def current_job():
record = json.loads(RECORD.read_text())
job_id = record["id"]
return api("GET", "/v1/jobs/" + quote(job_id, safe=""))["data"]["job"]
command = sys.argv[1] if len(sys.argv) == 2 else ""
if command == "submit":
# 기존 작업 ID가 있으면 덮어쓰거나 새 요청을 보내지 않습니다.
with RECORD.open("x") as saved:
saved.write('{}')
accepted = api("POST", "/v1/video/generations", {
"model": "dreamina-seedance-2.5",
"prompt": "바람에 천천히 흔들리는 초원의 풀을 고정 카메라로 촬영한 영상",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9",
"generate_audio": True,
"store_media": False,
})
RECORD.write_text(json.dumps({"id": accepted["id"]}))
print("접수한 작업 ID:", accepted["id"])
elif command == "status":
job = current_job()
print("작업:", job["id"], "상태:", job["status"])
for media in job.get("result", {}).get("media", []):
print("파일:", media["media_id"], media["kind"], media["state"])
if media.get("url_unavailable_reason"):
print("파일 링크를 사용할 수 없는 이유:", media["url_unavailable_reason"])
if "usage" in job:
print("작업 비용:", json.dumps(job["usage"], ensure_ascii=False))
elif job.get("status") == "failed":
print("실패한 작업입니다. 비용을 기다리며 반복 조회하지 말고 오류 내용을 확인하세요.")
else:
print("작업 비용이 아직 응답에 없습니다. 성공한 작업의 비용이 계속 없으면 작업 ID로 문의하세요.")
if "error" in job:
print("작업 오류 유형:", job["error"]["type"])
elif command == "download":
job = current_job()
if job["status"] == "failed":
raise SystemExit("작업이 실패했습니다. status로 같은 작업 ID의 오류 유형을 확인하세요.")
if job["status"] != "succeeded":
raise SystemExit("작업이 대기 또는 처리 중입니다. 잠시 뒤 status로 같은 작업 ID를 다시 확인하세요.")
videos = [m for m in job.get("result", {}).get("media", []) if m["kind"] == "video"]
if not videos:
raise SystemExit("영상 결과가 없습니다. status로 작업 상태를 확인하세요.")
if any(media.get("state") == "unavailable" for media in videos):
raise SystemExit("영상 파일을 지금 사용할 수 없습니다. status로 같은 작업 ID의 파일 상태와 이유를 확인하고 필요하면 문의하세요.")
if any(media.get("state") != "ready" for media in videos):
raise SystemExit("영상 파일이 준비 중입니다. 잠시 뒤 status로 같은 작업 ID의 파일 상태를 다시 확인하세요.")
for index, media in enumerate(videos, 1):
link = api("POST", "/v1/media/" + quote(media["media_id"], safe="") + "/link")
output = Path(f"video-{index}.mp4")
# 다운로드 URL에는 API 키 헤더를 보내지 않습니다.
with urlopen(link["url"], timeout=60) as response, output.open("xb") as target:
while chunk := response.read(1024 * 1024):
target.write(chunk)
print("다운로드 완료:", output, output.stat().st_size, "bytes")
else:
raise SystemExit("사용법: python3 video_job.py submit|status|download")새 작업을 시작할 때
터미널에서 video_job.py를 저장한 폴더로 이동해 다음 명령을 실행합니다. 예제의 명령 가운데 이 명령만 새 영상 생성 요청을 보냅니다.
python3 video_job.py submit작업 ID가 출력되고 video-job.json에 저장됐는지 확인한 뒤 같은 작업의 조회와 다운로드로 이어갑니다.
작업 ID가 있을 때
이미 작업 ID가 있다면 그 ID를 video_job.py와 같은 폴더의 video-job.json에 아래처럼 저장한 뒤 python3 video_job.py status로 이어갑니다. submit은 실행하지 않습니다. 기존 기록 파일이 있다면 새 폴더에 video_job.py와 video-job.json을 저장해 진행하세요. 그러면 다른 작업의 기록과 다운로드 파일을 그대로 보존할 수 있습니다.
{"id": "이미 확보한 작업 ID"}같은 작업의 조회와 다운로드
준비한 작업 기록으로 status를 실행해 상태를 확인합니다. 작업이 succeeded이고 영상 파일이 ready이면 download를 실행합니다. 기존 작업을 확인할 때는 submit을 실행하지 않습니다.
| 명령 | 확인할 결과 |
|---|---|
python3 video_job.py submit | 작업 ID 출력, video-job.json에 ID 저장 |
python3 video_job.py status | 같은 작업의 상태 출력, 비용이 제공되면 비용도 출력 |
python3 video_job.py download | 작업이 succeeded이고 영상 파일이 ready일 때 video-1.mp4부터 저장, 다운로드 완료 메시지 출력 |
예제는 기존 작업 기록과 영상 파일을 덮어쓰지 않습니다. 상황에 따라 다음처럼 이어 가세요.
| 상황 | 다음 행동 |
|---|---|
| 작업이 대기 또는 처리 중 | 잠시 뒤 status를 다시 실행. 코드의 60초는 HTTP 요청 제한시간이며 영상 생성 완료시간이 아님 |
| 다운로드를 마침 | 파일 크기를 확인하고 영상이 재생되는지도 확인 |
접수 응답을 받지 못해 video-job.json이 {}인 채 남음 | 기록을 지우고 다시 생성하지 말고 접수 여부부터 확인. 나중에 ID를 확보했다면 {"id": "확보한 작업 ID"}로 기록을 복원 |
| 다운로드가 중단되어 파일을 일부만 받음 | 받은 파일을 확인한 뒤 다른 위치로 옮기고 download를 다시 실행 |
문제 해결
| 증상 | 다음 행동 |
|---|---|
| 생성 요청의 입력이 거절됨 | 요청 필드와 조합을 사용할 모델의 가이드에서 확인합니다 |
| 접수 응답을 받지 못함 | 생성 요청을 다시 보내지 말고 접수 여부부터 확인합니다 |
| 작업을 조회할 수 없음 | 작업 ID와 키의 스페이스를 확인합니다. 새 생성 요청을 자동으로 보내지 않습니다 |
작업이 failed | data.job.error로 실패 원인을 확인하고 입력을 수정하거나 문의합니다. 이미지 작업은 Image Generations의 작업 실패 사유에서 error.type별 대응을 확인합니다 |
| 다운로드에 실패함 | 파일의 준비 상태와 만료 여부를 결과 파일 받기에서 결과 종류별로 확인합니다 |
| 웹훅 알림이 오지 않음 | 같은 작업 ID로 상태를 조회해 결과를 확인합니다. 수신 주소가 2,048자를 넘으면 요청은 웹훅 없이 접수됩니다 |
| 비용이 계속 없거나 집계와 다름 | 조회 시각과 범위를 함께 확인합니다. 성공한 작업의 비용이 계속 없으면 작업 ID로 문의합니다 |
Python 예제는 오류 코드와 Retry-After만 표시합니다. 상세 응답이 필요하면 자신의 서버에서 비공개로 확인합니다. 오류 코드별 대응과 재시도 기준은 오류 처리에서 확인합니다.
문제가 해결되지 않으면 플랫폼 내 문의 기능에 스페이스 이름, 요청 시각, 모델 코드, 오류 코드와 확보한 작업 ID를 남깁니다. API 키, 서명 링크, 고객 입력 원문과 전체 응답을 공개 로그나 문의 내용에 포함하지 마세요.
다음 단계
받은 작업 비용은 고객 시스템에 있는 작업 기록에 연결하세요. 마지막 프레임 반환을 지원하는 모델로 여러 장면을 이어 만든다면 마지막 프레임을 다음 장면의 첫 프레임으로 지정할 수 있습니다.