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

# Text Generation

> 단일 게이트웨이로 주요 LLM을 호출하는 텍스트 생성 연동 가이드

WAND AIGC Text Generation은 하나의 API Token으로 GPT, Gemini, Claude, Grok, DeepSeek, GLM, Kimi, MiniMax 등 주요 LLM을 단일 게이트웨이에서 호출하는 서비스입니다. 게이트웨이는 프록시 방식으로 동작하므로 Context Window, 최대 출력, 모달리티 등 모델 스펙은 원본 제공사와 동일합니다. 토큰 발급과 쿼터 관리는 VOD API로, 모델 호출은 `text-aigc.vod-qcloud.com` 게이트웨이로 이루어집니다.

## API 정보

| 구분                         | Action / 경로                                                                      | 엔드포인트                          | 인증 방식                                                   |
| -------------------------- | -------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------- |
| 토큰 발급                      | `CreateAigcApiToken`                                                             | `vod.intl.tencentcloudapi.com` | TC3-HMAC-SHA256 서명 (SecretId/SecretKey)                 |
| 토큰 목록 조회                   | `DescribeAigcApiTokens`                                                          | `vod.intl.tencentcloudapi.com` | TC3-HMAC-SHA256 서명                                      |
| 토큰 삭제                      | `DeleteAigcApiToken`                                                             | `vod.intl.tencentcloudapi.com` | TC3-HMAC-SHA256 서명                                      |
| 쿼터 관리                      | `DescribeAigcQuotas` / `CreateAigcQuota` / `ModifyAigcQuota` / `DeleteAigcQuota` | `vod.intl.tencentcloudapi.com` | TC3-HMAC-SHA256 서명 (SDK 미반영, 서명 직접 계산)                  |
| 사용량 조회                     | `DescribeAigcUsageData`                                                          | `vod.intl.tencentcloudapi.com` | TC3-HMAC-SHA256 서명                                      |
| 모델 호출 (OpenAI Completions) | `POST /v1/chat/completions`                                                      | `text-aigc.vod-qcloud.com`     | `Authorization: Bearer {TOKEN}` 또는 `x-api-key: {TOKEN}` |
| 모델 호출 (OpenAI Responses)   | `POST /v1/responses`                                                             | `text-aigc.vod-qcloud.com`     | 동일                                                      |
| 모델 호출 (Anthropic Messages) | `POST /v1/messages`                                                              | `text-aigc.vod-qcloud.com`     | 동일                                                      |
| 통계 조회                      | `GET /v1/statistics`, `GET /v1/request-logs`, `GET /v1/models`                   | `text-aigc.vod-qcloud.com`     | 동일                                                      |

### 토큰 발급

`CreateAigcApiToken`에 `SubAppId`(VOD 애플리케이션 ID)를 전달하면 `ApiToken`이 반환됩니다. 토큰은 만료되지 않으며 계정당 최대 50개까지 발급할 수 있습니다. 생성 직후 조회나 삭제가 가능해지기까지 약 30초의 동기화 시간이 필요합니다. 서브 계정으로 토큰 API를 호출하려면 루트 계정에서 `vod:CreateAigcApiToken`, `vod:DeleteAigcApiToken` 액션을 허용하는 CAM 정책을 부여해야 합니다.

## 지원 엔진

### 프로토콜 매트릭스

| 프로토콜               | 경로                     | 주요 모델                                |
| ------------------ | ---------------------- | ------------------------------------ |
| OpenAI Completions | `/v1/chat/completions` | GPT, Gemini, Kimi, GK, GLM, DeepSeek |
| OpenAI Responses   | `/v1/responses`        | GPT (공식 권장)                          |
| Anthropic Messages | `/v1/messages`         | CD (Claude), MiniMax                 |

### 모델 목록

| 제공사         | 모델 ID                                                                                                                                                                                                                                                 | 입력                     | 출력  |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | --- |
| OpenAI      | `gpt-5.5`, `gpt-5.4-pro`, `gpt-5.4`, `gpt-5.4-nano`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-5.3-chat`, `gpt-5.2-chat`, `gpt-5.2`, `gpt-5.1`, `gpt-5.1-chat`, `gpt-5`, `gpt-5-mini`, `gpt-5-chat`, `gpt-5-nano`, `gpt-chat-latest`, `gpt-4.1`, `gpt-4o` | 텍스트, 이미지               | 텍스트 |
| Gemini      | `gemini-3.5-flash`, `gemini-3.1-pro-preview`, `gemini-3.1-flash-lite`, `gemini-3.1-flash-lite-preview`, `gemini-3-flash-preview`, `gemini-2.5-pro`, `gemini-2.5-flash`                                                                                | 텍스트, 코드, 이미지, 오디오, 비디오 | 텍스트 |
| CD (Claude) | `cd-opus-4.8`, `cd-opus-4.7`, `cd-opus-4.6`, `cd-opus-4.5`, `cd-sonnet-4.6`, `cd-sonnet-4.5`, `cd-haiku-4.5`                                                                                                                                          | 텍스트, 이미지               | 텍스트 |
| GK (Grok)   | `gk-4.3`, `gk-4-20-reasoning`, `gk-4-20-non-reasoning`, `gk-4-1-fast-reasoning`, `gk-4.1-fast-non-reasoning`                                                                                                                                          | 텍스트, 이미지               | 텍스트 |
| DeepSeek    | `deepseek-v4-pro`, `deepseek-v4-flash`, `deepseek-v3.2`                                                                                                                                                                                               | 텍스트                    | 텍스트 |
| GLM         | `glm-5.1`, `glm-5`, `glm-5-turbo`                                                                                                                                                                                                                     | 텍스트                    | 텍스트 |
| Kimi        | `kimi-k2.6`, `kimi-k2.5`                                                                                                                                                                                                                              | 텍스트                    | 텍스트 |
| MiniMax     | `minimax-m2.7`, `minimax-m2.5`                                                                                                                                                                                                                        | 텍스트                    | 텍스트 |

호출 가능한 모델 ID는 `GET /v1/models`로 실시간 조회할 수 있습니다.

## 요청 파라미터

OpenAI Completions 기준입니다. Anthropic Messages와 Responses는 각 프로토콜의 공식 스펙을 따릅니다.

| 파라미터               | 타입            | 필수 여부 | 예시                                 | 설명                                                                                                                                   |
| ------------------ | ------------- | ----- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `model`            | String        | 필수    | `gpt-5.1`                          | 모델 ID                                                                                                                                |
| `messages`         | Array         | 필수    | `[{"role":"user","content":"Hi"}]` | 각 메시지는 `role`(`system`/`user`/`assistant`/`tool`)과 `content`로 구성. `content`는 문자열 또는 Part 배열(`text`/`image_url`/`input_audio`/`file`) |
| `stream`           | Boolean       | 필수    | `true`                             | `true`이면 SSE 스트리밍 응답                                                                                                                 |
| `thinking_enabled` | Boolean       | 선택    | `true`                             | 추론(CoT) 모드 활성화. 지원 모델 한정                                                                                                             |
| `reasoning_effort` | String        | 선택    | `high`                             | `none` / `minimal` / `low` / `medium` / `high` / `xhigh`. `thinking_enabled`와 함께 지정하면 우선 적용                                          |
| `temperature`      | Float         | 선택    | `0.7`                              | 출력 무작위성 (0\~2, 기본값 0.7). 추론 모델에서는 무시되거나 거부될 수 있음                                                                                     |
| `max_tokens`       | Integer       | 선택    | `1024`                             | 최대 생성 토큰 수                                                                                                                           |
| `tools`            | Array         | 선택    | Function 정의 배열                     | Function Calling. 전 모델 지원 (Gemini는 function tool만)                                                                                   |
| `tool_choice`      | String/Object | 선택    | `auto`                             | `auto` / `none` / `required` / 특정 도구 지정                                                                                              |
| `response_format`  | Object        | 선택    | `{"type":"json_object"}`           | JSON 강제 출력                                                                                                                           |

이미지 입력은 data URL 스킴을 지원하며 파일 크기는 70MB 이하여야 합니다.

## 응답 및 결과 조회

Text Generation은 동기 API이므로 TaskId 폴링이 없습니다. `stream=false`이면 완성된 응답을 한 번에, `stream=true`이면 SSE 이벤트 스트림으로 즉시 반환합니다.

토큰 사용량은 응답의 `usage` 필드로 확인합니다.

* `total_tokens = prompt_tokens + completion_tokens`
* `reasoning_tokens`는 `completion_tokens`에 포함됩니다 (별도 가산 아님)
* 캐시 적중량은 `usage.prompt_tokens_details.cached_tokens`에서 확인합니다

기간별 사용량과 요청 로그는 다음 채널로 조회합니다.

| 채널                                | 용도                                                                               | 제한                                                     |
| --------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `DescribeAigcUsageData` (VOD API) | Specification별 기간 사용량. Text는 `{model}_input` / `_output` / `_cacheinput`으로 집계    | 최근 365일 범위, 단일 조회 90일 이하. 1일 초과 기간은 일 단위, 이하는 5분 단위 집계 |
| `GET /v1/statistics` (게이트웨이)      | 모델별/API Key별 실시간 통계 (요청 수, 에러율, 토큰, 캐시 적중률, TTFT). `granularity`는 `1m`/`5m`/`1h` | 2 req/s. 1m/5m 데이터는 31일, 1h는 90일 보관                    |
| `GET /v1/request-logs` (게이트웨이)    | 요청 단위 로그 (모델, 상태 코드, 토큰, TTFT, TPS, 전체 지연). keyset cursor(`scroll_token`) 페이징    | 2 req/s                                                |

`v1/statistics`와 `v1/request-logs`는 테넌트가 격리되어 있어, API Key의 `OwnerAppid`와 쿼리의 `owner_app_id`(`app_id`)가 일치하지 않으면 `403 permission_denied`가 반환됩니다.

## 호출 예시

<Tabs>
  <Tab title="OpenAI Completions">
    ```bash theme={null}
    curl -X POST https://text-aigc.vod-qcloud.com/v1/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ${API_TOKEN}" \
      -d '{
        "model": "gpt-5.1",
        "stream": true,
        "stream_options": {"include_usage": true},
        "messages": [
          {"role": "user", "content": "who are you?"}
        ]
      }'
    ```

    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://text-aigc.vod-qcloud.com/v1"
    )

    response = client.chat.completions.create(
        model="gpt-5.1",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Hi, how are you?"},
        ],
    )
    print(response.choices[0].message.content)
    ```
  </Tab>

  <Tab title="Anthropic Messages">
    ```bash theme={null}
    curl https://text-aigc.vod-qcloud.com/v1/messages \
      -H "Content-Type: application/json" \
      -H "x-api-key: ${API_TOKEN}" \
      -d '{
        "max_tokens": 1024,
        "messages": [{"content": "Hello, world", "role": "user"}],
        "model": "cd-sonnet-4.6"
      }'
    ```

    ```python theme={null}
    import anthropic

    client = anthropic.Anthropic(
        api_key="YOUR_API_KEY",
        base_url="https://text-aigc.vod-qcloud.com/"
    )

    message = client.messages.create(
        model="cd-sonnet-4.6",
        max_tokens=1000,
        messages=[
            {"role": "user", "content": [{"type": "text", "text": "Hi, how are you?"}]}
        ]
    )
    print(message.content)
    ```
  </Tab>

  <Tab title="OpenAI Responses">
    ```bash theme={null}
    curl https://text-aigc.vod-qcloud.com/v1/responses \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ${API_TOKEN}" \
      -d '{
        "model": "gpt-5.1",
        "instructions": "You are a helpful assistant.",
        "input": "Hello!",
        "stream": true
      }'
    ```

    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://text-aigc.vod-qcloud.com/v1"
    )

    response = client.responses.create(
        model="gpt-5.1",
        input="Hello, how are you?",
        stream=True
    )
    for event in response:
        print(event)
    ```
  </Tab>
</Tabs>

## 응답 예시

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "gpt-5.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I am a large language model accessed through the WAND AIGC gateway."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 24,
    "total_tokens": 36,
    "prompt_tokens_details": {
      "cached_tokens": 0
    }
  }
}
```

## 주의사항

<Warning>
  계정/토큰 기본 레이트 리밋은 30 RPM, 300K TPM입니다. 쿼터 초과 시 HTTP 429와 `insufficient_quota` 오류가 반환됩니다.
</Warning>

<Warning>
  쿼터는 자동 리셋되지 않으며 비동기 집계 특성상 최대 +38%까지 초과 집계될 수 있습니다. 의도한 상한의 60\~70% 수준으로 `QuotaLimit`을 설정하고, 누적 카운터를 초기화하려면 `DeleteAigcQuota` 후 `CreateAigcQuota`로 재생성해야 합니다. `ModifyAigcQuota`는 누적값을 초기화하지 않습니다.
</Warning>

<Note>
  쿼터 관리 4개 API는 SDK 모델에 반영되어 있지 않아 TC3-HMAC-SHA256 서명을 직접 계산한 raw POST로만 호출할 수 있습니다. Text 쿼터는 ApiToken 단위이므로 `ApiToken` 파라미터가 필수이고, Image/Video 쿼터는 SubAppId 단위입니다.
</Note>

<Note>
  추론 모델은 `temperature`, `top_p`, `top_k`를 무시하거나 거부하는 경우가 많으므로 `reasoning_effort`로 제어합니다. `top_k`는 Anthropic/Gemini 경로에서만 유효합니다. 이미지 생성 출력은 지원하지 않으며 텍스트 출력만 가능합니다.
</Note>

<Note>
  DeepSeek는 `deepseek-v4-pro`, `deepseek-v4-flash`로만 호출할 수 있으며 `deepseek-v4` 단독 ID는 사용할 수 없습니다. 요청 취소 전용 API는 없고 HTTP 연결 종료로만 중단할 수 있으며, 과금 기준은 `DescribeAigcUsageData` 조회 결과입니다.
</Note>