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

# 빠른 통합

> EvoLink로 이미지, 비디오, 텍스트 모델을 빠르게 호출하기

# 빠른 통합

이 가이드는 몇 분 안에 EvoLink의 첫 호출을 완료하도록 돕습니다. 멀티모달 작업은 비동기 작업 방식을 사용하고, 텍스트 모델은 대화와 코딩 도구에 적합한 동기 Messages API를 사용합니다.

<CardGroup cols={3}>
  <Card title="이미지 생성" icon="image" href="/ko/api-manual/image-series/gpt-image-2/gpt-image-2-image-generation">
    GPT Image 2로 이미지 생성 작업을 만들고 작업 API를 통해 결과를 조회합니다.
  </Card>

  <Card title="비디오 생성" icon="video" href="/ko/api-manual/video-series/seedance2.0/seedance-2.0-overview">
    Seedance 2.0으로 텍스트-비디오, 이미지-비디오, 참조-비디오 작업을 생성합니다.
  </Card>

  <Card title="텍스트 생성" icon="comments" href="/ko/api-manual/language-series/claude/claude-messages-api">
    Claude Messages API를 사용해 동기 텍스트 응답을 받습니다.
  </Card>
</CardGroup>

## 준비

<Steps>
  <Step title="API Key 생성">
    [EvoLink 대시보드](https://evolink.ai/dashboard/keys)를 열고 API Key를 만든 뒤 안전하게 저장합니다.
  </Step>

  <Step title="Base URL 선택">
    이미지, 비디오, 오디오 등 멀티모달 작업에는 `https://api.evolink.ai`를 사용합니다. 텍스트 모델에는 `https://direct.evolink.ai`를 사용합니다.
  </Step>

  <Step title="요청 전송">
    멀티모달 API는 먼저 작업 ID를 반환합니다. 텍스트 API는 모델 응답을 직접 반환합니다.
  </Step>
</Steps>

<Warning>
  API Key는 계정 리소스를 호출할 수 있습니다. 서버 측이나 안전한 환경 변수에만 저장하세요. 프런트엔드 코드, 공개 저장소, 클라이언트 패키지에 키를 넣지 마세요.
</Warning>

## 요청 흐름

멀티모달 작업은 동일한 흐름을 사용합니다:

<CardGroup cols={3}>
  <Card title="1. 작업 제출" icon="paper-plane">
    이미지, 비디오 또는 오디오 엔드포인트를 호출하고 응답의 `id` 필드에서 작업 ID를 받습니다.
  </Card>

  <Card title="2. 상태 조회" icon="chart-line">
    `GET /v1/tasks/{task_id}`로 `pending`, `processing`, `completed`, `failed` 상태를 확인합니다.
  </Card>

  <Card title="3. 결과 가져오기" icon="download">
    작업이 완료되면 `results` 필드에서 생성 파일 URL을 읽습니다.
  </Card>
</CardGroup>

<Note>
  생성된 이미지와 비디오 URL은 일반적으로 만료됩니다. 운영 환경에서는 완료된 결과를 가능한 빨리 다운로드해 자체 스토리지에 저장하세요.
</Note>

## 이미지 생성

GPT Image 2로 이미지 생성 작업을 만듭니다:

```bash theme={null}
curl -X POST https://api.evolink.ai/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "해질녘 미래 도시 스카이라인을 영화적인 와이드 앵글로 묘사",
    "size": "16:9",
    "resolution": "4K",
    "quality": "high",
    "n": 1
  }'
```

응답은 작업 객체를 반환합니다:

```json theme={null}
{
  "id": "task-unified-1757156493-imcg5zqt",
  "object": "image.generation.task",
  "model": "gpt-image-2",
  "status": "pending",
  "progress": 0,
  "task_info": {
    "can_cancel": true,
    "estimated_time": 100
  }
}
```

작업 상태를 조회합니다:

```bash theme={null}
curl https://api.evolink.ai/v1/tasks/task-unified-1757156493-imcg5zqt \
  -H "Authorization: Bearer YOUR_API_KEY"
```

작업이 완료되면 결과가 `results` 배열에 표시됩니다:

```json theme={null}
{
  "id": "task-unified-1757156493-imcg5zqt",
  "object": "image.generation.task",
  "model": "gpt-image-2",
  "status": "completed",
  "progress": 100,
  "results": [
    "https://example.com/generated-image.png"
  ]
}
```

## 비디오 생성

Seedance 2.0으로 텍스트-비디오 작업을 만듭니다:

```bash theme={null}
curl -X POST https://api.evolink.ai/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-text-to-video",
    "prompt": "나뭇잎 위 초록색 유리개구리를 매크로로 촬영하고, 초점이 투명한 복부로 이동하면서 붉은 심장이 규칙적으로 뛰는 장면.",
    "duration": 8,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'
```

비디오 작업도 동일한 작업 API로 조회합니다:

```bash theme={null}
curl https://api.evolink.ai/v1/tasks/YOUR_VIDEO_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Tip>
  이미지-비디오 또는 다중 참조 비디오 생성이 필요하면 [Seedance 2.0 전체 파라미터 가이드](/ko/api-manual/video-series/seedance2.0/seedance-2.0-overview)에서 시작하세요.
</Tip>

## 텍스트 생성

Claude 텍스트 모델은 `https://direct.evolink.ai`와 `/v1/messages` 엔드포인트를 사용합니다:

```bash theme={null}
curl -X POST https://direct.evolink.ai/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "EvoLink의 가치를 세 문장으로 소개해 주세요"
      }
    ]
  }'
```

텍스트 API는 메시지 객체를 동기적으로 반환합니다:

```json theme={null}
{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-5-20250929",
  "content": [
    {
      "type": "text",
      "text": "EvoLink는 통합 AI 서비스 게이트웨이를 제공합니다..."
    }
  ],
  "stop_reason": "end_turn"
}
```

## Python 예시

아래 예시는 이미지 작업을 제출하고, 상태를 폴링하고, 최종 결과를 읽는 전체 흐름입니다:

```python theme={null}
import os
import time
import requests

API_KEY = os.environ["EVOLINK_API_KEY"]
BASE_URL = "https://api.evolink.ai"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


def create_image_task(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/v1/images/generations",
        headers=headers,
        json={
            "model": "gpt-image-2",
            "prompt": prompt,
            "size": "1:1",
            "quality": "high",
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]


def wait_for_task(task_id: str, timeout_seconds: int = 300):
    started_at = time.time()

    while time.time() - started_at < timeout_seconds:
        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        if task["status"] == "completed":
            return task["results"]
        if task["status"] == "failed":
            raise RuntimeError(task.get("error", "Task failed"))

        time.sleep(5)

    raise TimeoutError("Task timed out")


task_id = create_image_task("흰 배경과 부드러운 스튜디오 조명의 깔끔한 제품 포스터")
results = wait_for_task(task_id)
print(results[0])
```

## 요청 빈도 제한

EvoLink의 요청 빈도 제한은 모델 단위로 설정됩니다.

모델에 따라 RPM, 동시성, 작업 제출 제한이 다를 수 있습니다. 실제 제한은 모델 유형, 업스트림 서비스 용량, 계정 등급, 실시간 가용성에 따라 달라집니다. 가벼운 텍스트 모델은 일반적으로 더 높은 요청 빈도를 지원하지만, 이미지와 비디오 생성 모델은 작업 시간이 길고 업스트림 리소스를 더 많이 사용하므로 제한이 상대적으로 낮을 수 있습니다.

비동기 생성 모델의 경우 API가 성공 응답을 반환했다는 것은 작업이 접수되었거나 생성되었다는 의미일 뿐, 작업 완료를 의미하지 않습니다. 고동시성 업무에서는 서버 측 큐를 구현하고 작업 조회 API 또는 콜백을 통해 최종 결과를 가져오는 것을 권장합니다.

HTTP 429 오류가 계속 발생하거나 더 높은 RPM 또는 동시성 제한이 필요한 경우 [support@evolink.ai](mailto:support@evolink.ai)로 문의하세요. 실제 사용 시나리오와 업스트림 가용 용량을 기준으로 평가합니다.

## 운영 환경 권장 사항

<CardGroup cols={2}>
  <Card title="키 관리" icon="shield">
    API Key는 환경 변수 또는 시크릿 관리 서비스에 저장하고, 환경별로 별도 키를 사용하세요.
  </Card>

  <Card title="작업 폴링" icon="clock">
    작업 유형에 맞게 폴링 간격을 설정하세요. 이미지 작업은 더 자주, 비디오 작업은 보통 더 낮은 빈도로 조회하는 것이 좋습니다.
  </Card>

  <Card title="오류 처리" icon="server">
    `failed` 상태와 HTTP 오류를 처리하고, 빈도 제한, 잔액 부족, 파라미터 오류에 대한 명확한 안내를 준비하세요.
  </Card>

  <Card title="결과 저장" icon="download">
    생성 결과 URL은 만료됩니다. 운영 환경에서는 완료된 파일을 자체 스토리지에 저장하세요.
  </Card>
</CardGroup>

## 다음 단계

<CardGroup cols={3}>
  <Card title="이미지 API" icon="image" href="/ko/api-manual/image-series/gpt-image-2/gpt-image-2-image-generation">
    GPT Image 2의 전체 파라미터, 예시, 응답 구조를 확인합니다.
  </Card>

  <Card title="비디오 API" icon="video" href="/ko/api-manual/video-series/seedance2.0/seedance-2.0-overview">
    Seedance 2.0의 텍스트-비디오, 이미지-비디오, 참조-비디오 기능을 확인합니다.
  </Card>

  <Card title="작업 관리" icon="list-check" href="/ko/api-manual/task-management/get-task-detail">
    작업 상태 조회, 결과 필드, 오류 구조를 확인합니다.
  </Card>
</CardGroup>