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

# Main APIs

> Chat Completions and Models API reference

## 1. Chat Completions

Interact with AI models for single-turn and multi-turn conversations.

**Endpoint**: `POST /v1/chat/completions`

**Key Parameters**:

| Parameter     | Type    | Required | Description                                                         |
| ------------- | ------- | -------- | ------------------------------------------------------------------- |
| `model`       | string  | Yes      | Model name, e.g. `gemini-2.5-flash`, `deepseek-ai/DeepSeek-V3-0324` |
| `messages`    | array   | Yes      | List of conversation messages                                       |
| `max_tokens`  | number  | No       | Maximum response length, default 1024                               |
| `temperature` | number  | No       | Creativity control, 0-2, default 1                                  |
| `stream`      | boolean | No       | Whether to stream response, default false                           |

**Message Format**:

```json theme={null}
{
  "role": "user|assistant|system",
  "content": "Message content"
}
```

**Complete Request Example**:

```json theme={null}
{
  "model": "gemini-2.5-flash",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant"},
    {"role": "user", "content": "Write a Python bubble sort algorithm"}
  ],
  "max_tokens": 500,
  "temperature": 0.7
}
```

**Response Format**:

```json theme={null}
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "gemini-2.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here's the AI response content..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 100,
    "total_tokens": 120
  }
}
```

**Text + Image -> Image Request Example**:

```bash theme={null}
curl -N -X POST "https://gateway.iotex.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOU_KAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Change this picture to watercolor style and only output the picture" },
          {
            "type": "image_url",
            "image_url": {
              "url": "data:image/png;base64,<Your input image base64>"
            }
          }
        ]
      }
    ],
    "max_tokens": 1024
  }'
```

**Image -> Text Request Example**:

```bash theme={null}
curl -N -X POST "https://gateway.iotex.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOU_KAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "What is in this image?" },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
            }
          }
        ]
      }
    ],
    "max_tokens": 300
  }'
```

## 2. Image Generations

Generate images from text prompts.

**Endpoint**: `POST /v1/images/generations`

**Request Example**:

```bash theme={null}
curl -X POST "https://gateway.iotex.ai/v1/images/generations" \
  -H "Authorization: Bearer YOU_KAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "A cyberpunk cat in a neon-lit street",
    "n": 1,
    "size": "1024x1024"
  }'
```

**Response Example**:

```json theme={null}
{
  "created": 1677858242,
  "data": [
    {
      "url": "https://..."
    }
  ]
}
```

## 3. Audio Transcriptions

Transcribe audio into the input language.

**Endpoint**: `POST /v1/audio/transcriptions`

**Request Example**:

```bash theme={null}
curl -X POST "https://gateway.iotex.ai/v1/audio/transcriptions" \
  -H "Authorization: Bearer YOU_KAPI_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@example.m4a" \
  -F "model=openai/whisper-large-v3" \
  -F "language=zh" \
  -F "prompt=This is a Chinese conversation with complete punctuation."
```

**Response Example**:

```json theme={null}
{
  "text": "Transcription content..."
}
```

## 4. List Available Models

View the list of currently available AI models.

**Endpoint**: `GET /v1/models`

**Response Example**:

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "gemini-2.5-flash",
      "object": "model",
      "created": 1677858242,
      "owned_by": "google"
    },
    {
      "id": "deepseek-ai/DeepSeek-V3-0324",
      "object": "model",
      "created": 1677858242,
      "owned_by": "deepseek"
    }
  ]
}
```