YiTuoToken
모델 카탈로그로그인
제13장 / 총 21장약 1분

13. 비동기 작업(비디오 / Midjourney)#

비디오 생성, Midjourney 이미지 생성 등 시간이 오래 걸리는 작업은 비동기 방식을 사용합니다: 작업을 제출해 즉시 id를 받은 다음, 폴링으로 결과를 조회합니다.

13.1 비디오 작업 제출#

POST /v1/video/create(별칭 POST /v1/videos)

파라미터타입필수설명
modelstring예비디오 모델명(sora / veo / wan / doubao 계열 등)
promptstring아니오텍스트 설명(content와 둘 중 하나만 사용 가능, 동시 전달 불가)
contentarray아니오멀티모달 콘텐츠 배열. 텍스트 요소는 {"type":"text","text":"…"}, 참조 요소는 {"type":"image_url","image_url":{"url":"…"}}(video_url, audio_url도 동일하게 필드명이 type과 일치). 참조에는 role 지정 가능(reference_image, reference_video, reference_audio — 오디오 기반 생성 시 참조 오디오 전달). URL은 http(s), asset:, data: 지원
inputobject아니오Sora 스타일 중첩 입력
parametersobject아니오Wan 스타일 파라미터 블록(같은 이름의 최상위 필드가 parameters 내 값보다 우선)
imagesarray아니오참조 이미지 URL 목록(이미지→비디오, http/https URL이어야 함)
aspect_ratio / ratiostring아니오화면 비율, 예: 16:9(둘은 동등하며 ratio가 우선)
resolutionstring아니오해상도, 예: 720p / 1080p
durationinteger아니오비디오 길이(초), 1–15. Seedance 계열은 4–15
generate_audioboolean아니오오디오 포함 비디오 생성 여부. 오디오 출력을 지원하는 모델(예: Veo 3, 오디오 지원 Seedance)에만 적용되며, 미지원 모델은 업스트림에서 오류 발생. 미지정 시 채널 기본값 따름
watermarkboolean아니오워터마크 추가 여부
seedinteger아니오랜덤 시드(0–4294967295), 결과 재현용
return_last_frameboolean아니오결과에 비디오 마지막 프레임 반환 여부
enhance_promptboolean아니오업스트림이 프롬프트를 보강할지 여부
enable_upsampleboolean아니오업샘플링 활성화 여부
execution_expires_afterinteger아니오작업 보관 시간(초), 1–172800. 경과 후 작업 만료
Shell
# 기본 텍스트→비디오
curl http://183.240.79.21:52099/v1/video/create \
  -H "Authorization: Bearer sk-你的YiTuoToken-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "一只在草地上奔跑的柯基犬，阳光明媚",
    "aspect_ratio": "16:9"
  }'

# 오디오 포함 비디오 생성(지원 모델에 generate_audio: true 전달)
curl http://183.240.79.21:52099/v1/video/create \
  -H "Authorization: Bearer sk-你的YiTuoToken-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3",
    "prompt": "海浪拍打礁石，伴随海鸥鸣叫",
    "resolution": "1080p",
    "generate_audio": true
  }'

제출에 성공하면 작업 id가 반환되며, 이를 통해 작업 상태를 폴링합니다(13.3 참조). generate_audio는 업스트림에 그대로 전달됩니다. 대상 모델이 오디오를 지원하지 않으면 업스트림에서 작업 내 오류가 발생하며, 13.3 조회 결과의 error 필드에서 원인을 확인할 수 있습니다.

13.2 Midjourney 작업 제출#

엔드포인트설명
POST /v1/mj/submit/imagine텍스트→이미지
POST /v1/mj/submit/blend여러 이미지 블렌딩
POST /v1/mj/submit/action기존 작업에 업스케일 / 변형 등의 조작 수행
cURL
curl http://183.240.79.21:52099/v1/mj/submit/imagine \
  -H "Authorization: Bearer sk-你的YiTuoToken-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "midjourney",
    "prompt": "a cute corgi astronaut, digital art --ar 16:9"
  }'

13.3 작업 상태 조회#

GET /v1/tasks/{id} — 제출 시 반환된 id로 조회합니다. 작업 소유 검증: 다른 사람의 작업을 조회하면 404가 반환됩니다(열거 방지). ?fresh=true를 붙이면 업스트림 실시간 폴링이 한 번 실행됩니다.

cURL
curl http://183.240.79.21:52099/v1/tasks/0000019f-... \
  -H "Authorization: Bearer sk-你的YiTuoToken-Key"

13.4 작업 목록#

GET /v1/tasks — 자신의 작업을 나열합니다(생성 시간 내림차순).

쿼리 파라미터설명
task_type유형별 필터(예: video, mj)
status상태별 필터
offset오프셋, 기본값 0
limit페이지당 수량, 기본값 50, 최대 200
cURL
curl "http://183.240.79.21:52099/v1/tasks?task_type=video&limit=20" \
  -H "Authorization: Bearer sk-你的YiTuoToken-Key"

13.5 작업 취소#

POST /v1/tasks/{id}/cancel — 진행 중인 작업을 취소하고 사전 동결된 쿼터의 동결을 해제합니다. 작업이 존재하지 않거나 이미 종료 상태이면 404가 반환됩니다.

cURL
curl -X POST http://183.240.79.21:52099/v1/tasks/0000019f-.../cancel \
  -H "Authorization: Bearer sk-你的YiTuoToken-Key"