Ark 텍스트-투-비디오

Base URL

https://api.yourouter.ai

인증

모든 요청에 다음 헤더 중 하나를 포함해야 합니다.

Authorization: Bearer <YOUROUTER_API_KEY>
x-api-key: <YOUROUTER_API_KEY>

모든 요청에 Content-Type: application/json을 포함해야 합니다. 각 응답에는 추적 및 문제 해결을 위한 x-request-id 헤더가 포함됩니다.

동작 방식

클라이언트가 게이트웨이를 호출하여 Ark 공식 API와 동일한 요청 본문으로 작업을 생성합니다.
게이트웨이는 즉시 Ark가 생성한 작업 ID를 반환하고 조직, 모델, Ark 키, 채널, 상태 등 작업 관련 정보를 저장합니다.
미완료 작업에 대해 게이트웨이는 저장된 Ark API 키로 10초마다 한 번씩 폴링합니다.
과금 시 성공 결과의 usage.completion_tokens를 읽습니다.

응답의 video_url은 Ark가 반환한 서명된 임시 링크이며 유효 기간은 86,400초(24시간)입니다. 만료 전에 영상을 다운로드하세요.

작업 생성

엔드포인트: POST /api/v3/contents/generations/tasks 요청 본문은 Ark 공식 API와 동일합니다. 예시:

curl -X POST https://api.yourouter.ai/api/v3/contents/generations/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $YOUROUTER_API_KEY" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [
      {
        "type": "text",
        "text": "Drone races through obstacles at high speed for an immersive flight experience  --resolution 1080p  --duration 5 --camerafixed false --watermark true"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://ark-project.tos-cn-beijing.volces.com/doc_image/seepro_i2v.png" }
      }
    ]
  }'

성공 응답(생성 단계에서는 보통 Ark 작업 ID만 반환):

{ "id": "cgt-20250906194036-2k4r4" }

게이트웨이는 이 ID를 모델, 조직, Ark 키, 채널, 상태 등과 함께 저장하고 백그라운드 폴링을 시작합니다.

작업 조회

엔드포인트: GET /api/v3/contents/generations/tasks/{id} 이 인터페이스는 게이트웨이 데이터베이스에서 작업 결과를 반환합니다. 작업이 아직 생성 중이면 응답에 현재 상태가 포함되고, 완료되면 Ark의 전체 결과를 반환하며 id와 vendor 필드를 주입합니다.

curl -X GET https://api.yourouter.ai/api/v3/contents/generations/tasks/cgt-20250906194036-2k4r4 \
  -H "Authorization: Bearer $YOUROUTER_API_KEY"

실행 중 예시:

{ "id": "cgt-20250906194036-2k4r4", "status": "RUNNING" }

완료 예시:

{
  "id": "your-00000000000000000000000000000000",
  "model": "doubao-seedance-1-0-pro-250528",
  "status": "succeeded",
  "content": {
    "video_url": "https://ark-content-generation-cn-beijing.tos-cn-beijing.volces.com/doubao-seedance-1-0-pro/....mp4?...&X-Tos-Expires=86400&..."
  },
  "usage": {
    "completion_tokens": 246840,
    "total_tokens": 246840
  },
  "created_at": 1757158837,
  "updated_at": 1757158914,
  "seed": 95409,
  "resolution": "1080p",
  "duration": 5,
  "ratio": "16:9",
  "framespersecond": 24,
  "vendor": "Ark"
}

과금

status가 succeeded일 때만 사용량이 기록됩니다.
성공 결과의 usage.completion_tokens는 텍스트 completion 사용량으로 과금되며, 값은 Ark가 반환한 것과 동일합니다.

상태 값

RUNNING: 게이트웨이가 Ark를 폴링 중입니다.
SUCCEEDED: 최종 결과를 가져와 저장했으며, 이후 조회 시 전체 결과가 반환됩니다.
NOT_FOUND: 게이트웨이에 해당 작업 ID가 없습니다. 작업이 없거나 정리되었을 수 있습니다.

오류 및 상태 코드

401/403: API 키 누락 또는 무효, 조직 비활성화, 잔액 부족 등.
200 + body: 조회 인터페이스는 항상 HTTP 200을 반환하며, 작업 상태는 JSON 본문으로 전달됩니다.
5xx: 내부 서비스 오류 또는 Ark 사용 불가. 재시도를 권장합니다.

사용 권장 사항

작업은 5~10초 간격으로 폴링하세요. 게이트웨이는 Ark를 10초마다 폴링합니다.
문제 해결을 위해 응답의 x-request-id를 보관하세요.
video_url이 만료되면 새 링크를 얻기 위해 작업을 다시 생성해야 합니다. Ark는 현재 갱신을 지원하지 않습니다.
동일 콘텐츠를 반복 제출하지 마세요. 현재 멱등 키는 없습니다.

시작하기

모델 API

라우팅 및 안정성

API 레퍼런스

기능

법무

Base URL

인증

동작 방식

작업 생성

작업 조회

과금

상태 값

오류 및 상태 코드

사용 권장 사항

​Base URL

​인증

​동작 방식

​작업 생성

​작업 조회

​과금

​상태 값

​오류 및 상태 코드

​사용 권장 사항

Base URL

인증

동작 방식

작업 생성

작업 조회

과금

상태 값

오류 및 상태 코드

사용 권장 사항