API 문서 · 에셋

에셋 업로드

단일 업로드, 멀티파트 업로드 및 URL 가져오기.

에셋을 먼저 플랫폼에 업로드한 뒤 작업의 inputs에서 asset_id로 참조합니다. 같은 에셋을 여러 작업에서 재사용할 수 있습니다. 파일 하나의 최대 크기는 2 GiB이며, 업로드 세션은 1시간 동안 유효합니다(반환되는 expires_at 참고).

단일 업로드

파일이 100 MB 이하이면 POST /v1/uploads가 method: "single"과 미리 서명된 upload_url을 반환합니다. 반환된 headers를 포함해 PUT으로 파일 본문을 업로드한 다음 complete를 호출하세요.

멀티파트 업로드

더 큰 파일은 method: "multipart"와 함께 part_size(보통 16.0 MB), part_count를 반환합니다.

POST /v1/uploads/{id}/parts에 { "part_numbers": [1, 2, …] }(요청당 최대 100개)를 보내면 { "parts": [{ "part_number": 1, "url": "…" }] }가 반환됩니다.
파일을 순서대로 나눠 각 파트를 PUT하고, 응답 헤더의 ETag를 기록합니다.
{ "parts": [{ "part_number": 1, "etag": "…" }] }로 complete를 호출합니다.

URL 가져오기

POST /v1/assets에 upload_id 대신 source_url을 전달하면 플랫폼이 해당 주소에서 파일을 가져옵니다. http / https 공개 주소만 지원하며, 파일은 250 MB 이하이고 60초 안에 다운로드가 끝나야 합니다. 가져오기와 저장에 성공해야만 에셋이 장기 보관됩니다. 가져오기에 실패하면 상태가 failed로 바뀌고 status_reason에 원인이 표시됩니다.

에셋 상태

status	의미
업로드 중	URL 가져오기: 파일을 가져오는 중
처리 중	플랫폼이 형식, 크기, 길이를 분석하고 콘텐츠 심사를 진행하는 중
사용 가능	작업에 사용 가능
승인 필요	실존 인물(real_person)로 지정된 에셋. 실존 인물 승인 필요
실패	형식 불일치, 가져오기 실패, 콘텐츠 심사 미통과 또는 체크섬 불일치. status_reason 참고
삭제 중	삭제 요청됨. 진행 중인 작업이 아직 참조하고 있으면 작업 종료 후 정리

에셋이 available이 되기 전에 작업을 제출하면 422 asset_not_ready(재시도 가능)를 반환합니다.

# 1. 업로드 요청
curl https://cn-api.aitoken.tools/v1/uploads \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"hero.png","content_type":"image/png","size_bytes":1832211}'

# 2. 반환된 upload_url로 파일을 PUT(반환된 headers 포함)
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @hero.png

# 3. 업로드 완료
curl -X POST https://cn-api.aitoken.tools/v1/uploads/upl_xxx/complete \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

# 4. 소재 생성
curl https://cn-api.aitoken.tools/v1/assets \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"upl_xxx","name":"hero"}'