> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# SeeDream Tasks API의 연동 및 사용
> ByteDance Seedream Image Generation 集成指南 - XHuoAPI
SeeDream Tasks API의 주요 기능은 SeeDream Images Generation API에서 생성된 작업 ID를 입력하여 해당 작업의 실행 상태를 조회하는 것입니다.
본 문서는 SeeDream Tasks API의 연동 설명을 자세히 소개하여, 귀하가 이 API의 강력한 기능을 쉽게 통합하고 충분히 활용할 수 있도록 돕습니다. SeeDream Tasks API를 통해 SeeDream Images Generation API의 작업 실행 상태를 쉽게 조회할 수 있습니다.
## 신청 절차
SeeDream Tasks API를 사용하려면 먼저 신청 페이지 [SeeDream Images Generation API](https://api.xhuoapi.ai/documents/seedream-images)에서 해당 서비스를 신청한 후, SeeDream Images Generation API의 작업 ID를 복사해야 합니다. 아래 그림과 같이 진행합니다:
마지막으로 Tasks API 페이지 [SeeDream Tasks API](https://api.xhuoapi.ai/documents/seedream-tasks)에서 해당 서비스를 신청하고, 페이지에 들어가면 「Acquire」 버튼을 클릭합니다. 아래 그림과 같이 진행합니다:
로그인 또는 등록이 되어 있지 않은 경우, 자동으로 [로그인 페이지](https://api.xhuoapi.ai)로 이동하여 등록 및 로그인을 요청합니다. 로그인 및 등록 후에는 자동으로 현재 페이지로 돌아옵니다.
첫 신청 시 무료 사용 한도가 제공되어, 해당 API를 무료로 사용할 수 있습니다.
## 요청 예시
SeeDream Tasks API는 SeeDream Images Generation API의 결과를 조회하는 데 사용할 수 있습니다. SeeDream Images Generation API 사용 방법에 대한 자세한 내용은 문서 [SeeDream Images Generation API](https://api.xhuoapi.ai/documents/seedream-images-integration)를 참조하십시오.
SeeDream Images Generation API 서비스에서 반환된 작업 ID를 예로 들어, 해당 API를 사용하는 방법을 시연합니다. 가정해 보겠습니다, 작업 ID가 20068983-0cc9-4c6a-aeb6-9c6a3c668be0이라고 할 때, 다음과 같이 작업 ID를 전달하여 진행합니다.
### 작업 예시 그림
### 요청 헤더 및 요청 본문 설정
**Request Headers**에는 다음이 포함됩니다:
* `accept`: JSON 형식의 응답 결과를 수신하도록 지정하며, 여기서는 `application/json`으로 입력합니다.
* `authorization`: API 호출에 필요한 키로, 신청 후 직접 드롭다운에서 선택할 수 있습니다.
**Request Body**에는 다음이 포함됩니다:
* `id`: 업로드된 작업 ID.
* `action`: 작업의 조작 방식.
아래 그림과 같이 설정합니다:
### 코드 예시
페이지 오른쪽에서 다양한 언어의 코드가 자동으로 생성된 것을 확인할 수 있습니다. 아래 그림과 같이 진행합니다:
일부 코드 예시는 다음과 같습니다:
#### CURL
```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/seedream/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"id": "a6e0d456-189b-4c78-9232-2fe72166ab39",
"action": "retrieve"
}'
```
### 응답 예시
요청이 성공하면, API는 해당 작업의 상세 정보를 반환합니다. 예를 들어:
```json theme={null}
{
"success": true,
"task_id": "84d1544a-9043-4dde-a98b-e889dacd75f6",
"trace_id": "176acf03-7ca7-4fc6-85db-e3724d4f59eb",
"data": [
{
"prompt": "a white siamese cat",
"size": "2048x2048",
"image_url": "https://platform.cdn.xhuoapi.ai/seedream/6e5f9085-cc4a-4801-b77b-31550129ff19.jpg"
}
]
}
```
반환 결과에는 여러 필드가 있으며, 설명은 다음과 같습니다:
* `success`: 현재 비디오 생성 작업의 상태.
* `task_id`: 현재 비디오 생성 작업 ID.
* `trace_id`: 현재 비디오 생성 추적 ID.
* `data`: 현재 이미지 생성 작업의 결과 목록.
* `image_url`: 현재 이미지 생성 작업의 링크.
* `prompt`: 프롬프트.
* `size`: 생성된 이미지의 픽셀.
## 배치 조회 작업
여러 작업 ID에 대한 작업 세부 정보를 조회하는 것으로, 위와 다른 점은 action을 retrieve\_batch로 선택해야 한다는 것입니다.
**Request Body**에는 다음이 포함됩니다:
* `ids`: 업로드된 작업 ID 배열.
* `action`: 작업의 조작 방식.
아래 그림과 같이 설정합니다:
### 코드 예시
일부 코드 예시는 다음과 같습니다:
### 응답 예시
요청이 성공하면, API는 이번 모든 배치 작업의 구체적인 상세 정보를 반환합니다. 예를 들어:
```json theme={null}
{
"items": [
{
"_id": "69498b9bff2676299c5cb7a6",
"id": "84d1544a-9043-4dde-a98b-e889dacd75f6",
"api_id": "86ad30f3-0bc8-4b9b-b019-b9fa5b05672e",
"application_id": "11e25072-de6d-4bd6-81e7-77ee0055499a",
"created_at": 1766427547.107,
"credential_id": "50892af9-597f-426e-a455-bc1739de95b0",
"request": {
"action": "generate",
"model": "doubao-seedream-4-0-250828",
"prompt": "하얀 색의 샴 고양이"
},
"trace_id": "176acf03-7ca7-4fc6-85db-e3724d4f59eb",
"type": "images",
"user_id": "b60a9491-1eba-4ab8-a93f-12c0fd81dab4",
"response": {
"success": true,
"task_id": "84d1544a-9043-4dde-a98b-e889dacd75f6",
"trace_id": "176acf03-7ca7-4fc6-85db-e3724d4f59eb",
"data": [
{
"prompt": "하얀 색의 샴 고양이",
"size": "2048x2048",
"image_url": "https://platform.cdn.xhuoapi.ai/seedream/6e5f9085-cc4a-4801-b77b-31550129ff19.jpg"
}
]
}
},
{
"_id": "69498b9bff2676299c5cb7a6",
"id": "84d1544a-9043-4dde-a98b-e889dacd75f6",
"api_id": "86ad30f3-0bc8-4b9b-b019-b9fa5b05672e",
"application_id": "11e25072-de6d-4bd6-81e7-77ee0055499a",
"created_at": 1766427547.107,
"credential_id": "50892af9-597f-426e-a455-bc1739de95b0",
"request": {
"action": "generate",
"model": "doubao-seedream-4-0-250828",
"prompt": "하얀 색의 샴 고양이"
},
"trace_id": "176acf03-7ca7-4fc6-85db-e3724d4f59eb",
"type": "images",
"user_id": "b60a9491-1eba-4ab8-a93f-12c0fd81dab4",
"response": {
"success": true,
"task_id": "84d1544a-9043-4dde-a98b-e889dacd75f6",
"trace_id": "176acf03-7ca7-4fc6-85db-e3724d4f59eb",
"data": [
{
"prompt": "하얀 색의 샴 고양이",
"size": "2048x2048",
"image_url": "https://platform.cdn.xhuoapi.ai/seedream/6e5f9085-cc4a-4801-b77b-31550129ff19.jpg"
}
]
}
}
],
"count": 2
}
```
반환 결과는 여러 필드를 포함하고 있으며, items는 배치 작업의 구체적인 세부 정보 정보를 포함하고 있습니다. 각 작업의 구체적인 정보는 위의 필드와 동일하며, 필드 정보는 다음과 같습니다.
* `items`, 배치 작업의 모든 구체적인 세부 정보. 이는 배열이며, 각 배열의 요소는 위의 단일 작업의 반환 결과 형식과 동일합니다.
* `count`, 이곳에서 배치 쿼리 작업의 개수입니다.
#### CURL
```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/seedance/tasks' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"ids": ["84d1544a-9043-4dde-a98b-e889dacd75f6","84d1544a-9043-4dde-a98b-e889dacd75f6"],
"action": "retrieve_batch"
}'
```
## 오류 처리
API를 호출할 때 오류가 발생하면, API는 해당 오류 코드와 정보를 반환합니다. 예를 들어:
* `400 token_mismatched`: 잘못된 요청, 누락되었거나 잘못된 매개변수로 인한 것일 수 있습니다.
* `400 api_not_implemented`: 잘못된 요청, 누락되었거나 잘못된 매개변수로 인한 것일 수 있습니다.
* `401 invalid_token`: 권한 없음, 잘못되었거나 누락된 인증 토큰입니다.
* `429 too_many_requests`: 너무 많은 요청, 비율 제한을 초과했습니다.
* `500 api_error`: 내부 서버 오류, 서버에서 문제가 발생했습니다.
### 오류 응답 예시
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "가져오기 실패"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## 결론
이 문서를 통해 SeeDream Tasks API를 사용하여 단일 또는 배치 작업의 모든 구체적인 세부 정보를 쿼리하는 방법을 이해하셨습니다. 이 문서가 API를 더 잘 연결하고 사용하는 데 도움이 되기를 바랍니다. 질문이 있으시면 언제든지 기술 지원 팀에 문의해 주십시오.