aisplice

API 레퍼런스

동영상

POST/v1/videos
GET/v1/videos/{task_id}
GET/v1/videos/{task_id}/content

비동기 동영상 생성(Seedance, Kling, Veo, Wan, Grok Imagine …). /v1/videos는 OpenAI 형식의 요청 하나로 텍스트→동영상과 이미지→동영상 입력을 모두 받습니다. 폴링할 task_id를 반환하며 — 제출 시 웹훅을 등록할 수도 있습니다.

#요청 파라미터

  • modelstring필수

    모델 페이지의 동영상 모델 ID(예: doubao-seedance-2.5).

  • promptstring필수

    장면 설명. image2video에서는 움직임을 제어합니다.

  • imagestring선택

    image2video 전용: 첫 프레임 이미지(URL 또는 base64).

  • imagesarray선택

    한 작업에 여러 이미지를 받는 제공업체용 참조 프레임.

  • durationnumber선택

    클립 길이(초) — 요금 구간 기준 중 하나입니다. 지원 값은 모델 카드를 참고하세요.

  • secondsnumber선택

    일부 모델 계열이 클립 길이에 쓰는 별칭입니다. duration을 우선 사용하세요.

  • resolutionstring선택

    모델이 지원하는 경우 720p, 1080p 같은 출력 해상도 구간.

  • sizestring선택

    너비 x 높이 방식의 크기를 쓰는 모델 계열용 화면 비율 또는 크기 선택값.

  • webhook_urlstring선택

    작업이 최종 상태에 도달하면 호출되는 HTTPS URL — 콜백 규약은 동영상 가이드를 참고하세요.

  • webhook_secretstring선택

    설정하면 전송에 X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret))가 포함됩니다.

제공업체 파라미터 패스스루

모델 계열마다 추가 제공업체 파라미터(aspect_ratio, cfg_scale, negative_prompt …)를 받으며 그대로 전달됩니다 — 모델 카드에 설명되어 있습니다. 알 수 없는 필드는 게이트웨이가 아니라 업스트림에서 거부됩니다.

실패한 작업은 자동 환불

동영상 작업은 제출 시 사전 차감되며, failed로 끝나면 전액 환불됩니다 — 원장에는 원래 차감 내역과 연결된 환불이 기록됩니다.

#실행 중인 작업 취소

DELETE/v1/videos/:task_id

아직 최종 상태에 도달하지 않은 작업을 중지합니다. 성공하면 사전 차감된 한도가 환불되고, 작업은 "cancelled by user" 사유와 함께 failed로 기록되며, 등록한 웹훅은 task.failed로 발송됩니다.

대부분의 제공업체는 취소를 지원하지 않음

취소 요청은 업스트림 제공업체로 전달되며, 일부 제공업체만 이를 지원합니다. 나머지는 모두 501 task_cancel_not_supported를 반환합니다. UI에서 취소는 최선의 시도로 다루세요. 폴링을 계속하고, 이 호출이 200을 반환하기 전에는 사용자에게 환불을 약속하지 마세요.
curl -X DELETE https://www.aisplice.store/v1/videos/task_xxx \
  -H "Authorization: Bearer sk-YOUR_KEY"
cancelled.json
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "status": "cancelled"
}

"cancelled"는 이 응답에만 나타납니다. 이후 폴링에서는 작업이 failed로 표시됩니다. 실제로 전환된 상태가 failed이기 때문입니다.

  • 404 task_not_exist알 수 없는 작업 ID이거나 다른 계정의 작업입니다.
  • 409 task_not_cancellable작업이 이미 끝났습니다 — 중지할 것이 없습니다.
  • 501 task_cancel_not_supported이 제공업체는 취소 API를 제공하지 않습니다.

전체 오류 코드 표 →

#기존 동영상 리믹스

POST/v1/videos/:video_id/remix

지원하는 모델에서 완성된 동영상을 새 프롬프트로 다시 생성합니다. prompt만 보내세요. 모델, 길이, 해상도, 요금 요소는 모두 원래 작업에서 상속되며, 요청은 원래 동영상을 생성한 채널에 고정됩니다.

curl https://www.aisplice.store/v1/videos/task_xxx/remix \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: remix-of-task_xxx" \
  -d '{"prompt": "Same shot, at night"}'
remix.json
{
  "task_id": "task_yyy",
  "status": "queued",
  "remixed_from_video_id": "task_xxx"
}

리믹스는 새로 과금되는 작업입니다

원래 작업과 같은 비용이 들고, 같은 수명 주기를 따르며, 별도의 task_id를 반환합니다. 새 ID로 폴링하세요 — 원래 작업은 영향을 받지 않습니다.
  • 400 invalid_request리믹스에는 prompt가 필수입니다.
  • 400 task_not_exist원본 동영상 ID를 알 수 없거나 다른 계정에 속해 있습니다.
  • 400 task_channel_disable원본 동영상을 생성한 채널이 더 이상 활성화되어 있지 않습니다.

전체 오류 코드 표 →

#관련 오류

  • 404 not_found알 수 없는 경로나 모델 이름, 또는 만료되었거나 다른 계정의 task_id입니다.
  • 422 unprocessable_entity게이트웨이가 전달한 파라미터 값을 제공업체가 거부했습니다(예: 지원하지 않는 크기나 길이).
  • 401Bearer 토큰이 유효하지 않거나 없습니다. 이 경로에는 error.code가 없으므로 상태 코드로 판단하세요.
  • 402 insufficient_user_quota지갑 잔액이 사전 차감 추정액보다 부족합니다.
  • 429키별 속도 제한입니다. 본문은 비어 있으며 Retry-After만큼 기다리세요. insufficient_user_quota가 포함된 429는 속도 제한이 아니라 일일 지출 한도입니다.
  • 503 model_not_found알 수 없는 모델이거나, 현재 이 모델을 제공하는 정상 채널이 없습니다.

전체 오류 코드 표 →

#요청 예시

# submit
curl https://www.aisplice.store/v1/videos \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "doubao-seedance-2.5", "prompt": "A drone shot of a lighthouse at dawn"}'

# poll every 5s
curl https://www.aisplice.store/v1/videos/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# download when completed
curl -L https://www.aisplice.store/v1/videos/$TASK_ID/content -o out.mp4 -H "Authorization: Bearer sk-YOUR_KEY"

#응답

response.json
// POST — submit accepted
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/videos/{task_id}
{
  "task_id": "task_xxx",
  "status": "in_progress",      // queued | in_progress | completed | failed
  "progress": "45%"
}

// terminal state
{
  "task_id": "task_xxx",
  "status": "completed",
  "metadata": {"url": "https://…"}
}

아직 해결되지 않았나요?

요청 ID나 오류 메시지를 보내 주시면 확인해 드리겠습니다.

이전이미지: 비동기 작업다음음악