> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yourouter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ark 텍스트-투-비디오

> YouRouter를 통해 Ark의 영상 생성 API를 호출합니다.

## Base URL

`https://api.yourouter.ai`

## 인증

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

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

모든 요청에 `Content-Type: application/json`을 포함해야 합니다.

각 응답에는 추적 및 문제 해결을 위한 `x-request-id` 헤더가 포함됩니다.

## 동작 방식

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

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

## 작업 생성

**엔드포인트**: `POST /api/v3/contents/generations/tasks`

요청 본문은 Ark 공식 API와 동일합니다. 예시:

```bash theme={null}
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만 반환):

```json theme={null}
{ "id": "cgt-20250906194036-2k4r4" }
```

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

## 작업 조회

**엔드포인트**: `GET /api/v3/contents/generations/tasks/{id}`

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

```bash theme={null}
curl -X GET https://api.yourouter.ai/api/v3/contents/generations/tasks/cgt-20250906194036-2k4r4 \
  -H "Authorization: Bearer $YOUROUTER_API_KEY"
```

**실행 중 예시**:

```json theme={null}
{ "id": "cgt-20250906194036-2k4r4", "status": "RUNNING" }
```

**완료 예시**:

```json theme={null}
{
  "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는 현재 갱신을 지원하지 않습니다.
* 동일 콘텐츠를 반복 제출하지 마세요. 현재 멱등 키는 없습니다.