# AI Studio — Eto API

> Generate listing titles, descriptions and images, and analyse product photos.

Base URL `https://eto.tools/api/v1/`. Every request carries the `X-Eto-API-Key` header. Part of the [Eto API reference](https://eto.tools/dev/docs/).

## Endpoints in this category

- [POST /api/v1/ai/chat](https://eto.tools/dev/docs/ai-studio/ai-chat.md): AI chat
- [POST /api/v1/ai/generate-title](https://eto.tools/dev/docs/ai-studio/ai-generate-title.md): AI: generate a listing title
- [POST /api/v1/ai/generate-description](https://eto.tools/dev/docs/ai-studio/ai-generate-description.md): AI: generate a listing description
- [POST /api/v1/ai/generate-image](https://eto.tools/dev/docs/ai-studio/ai-generate-image.md): AI: generate an image (async)
- [GET /api/v1/ai/generate-image/status](https://eto.tools/dev/docs/ai-studio/ai-generate-image-status.md): AI: image generation status
- [POST /api/v1/ai/analyze-image](https://eto.tools/dev/docs/ai-studio/ai-analyze-image.md): AI: analyze a product image

## POST /api/v1/ai/chat

AI chat

- Operation ID: `ai_chat`
- Slug: `ai-chat`
- Category: AI Studio
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-ai-chat
- Markdown: https://eto.tools/dev/docs/ai-studio/ai-chat.md

Free-form AI chat using your configured Gemini credentials. Requires AI credentials configured in Eto settings.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `message` | body | `string` | yes | The user message / prompt |
| `context` | body | `object` | no | Optional context object merged into the prompt |

### Request

```bash
curl -X POST "https://eto.tools/api/v1/ai/chat" \
  -H "X-Eto-API-Key: eto_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Suggest three tag ideas for a leather wallet listing."
}'
```

```python
import requests

url = "https://eto.tools/api/v1/ai/chat"
headers = {"X-Eto-API-Key": "eto_your_key"}
payload = {
    "message": "Suggest three tag ideas for a leather wallet listing."
}

response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
print(response.json())
```

```javascript
const url = "https://eto.tools/api/v1/ai/chat";
const payload = {
  "message": "Suggest three tag ideas for a leather wallet listing."
};

const response = await fetch(url, {
  method: "POST",
  body: JSON.stringify(payload),
  headers: {
    "X-Eto-API-Key": "eto_your_key",
    "Content-Type": "application/json",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

`application/json`. This endpoint has no worked response example in the registry yet; the [HTML reference](https://eto.tools/dev/docs/#ep-ai-chat) shows the fields it returns.

### Errors

Failures answer with the shared error body described in the Errors section: `{"error": {"code", "status", "message", "hint", "docs"}}`. Branch on `code`, not on the message.


## POST /api/v1/ai/generate-title

AI: generate a listing title

- Operation ID: `ai_generate_title`
- Slug: `ai-generate-title`
- Category: AI Studio
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-ai-generate-title
- Markdown: https://eto.tools/dev/docs/ai-studio/ai-generate-title.md

Generate an Etsy listing title for a keyword.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `keyword` | body | `string` | yes | Target keyword |
| `product_description` | body | `string` | no | Optional product description for context |
| `style` | body | `string` | no | Tone/style (default "professional") |
| `max_length` | body | `integer` | no | Max title length (capped at 200, default 140) |

### Request

```bash
curl -X POST "https://eto.tools/api/v1/ai/generate-title" \
  -H "X-Eto-API-Key: eto_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "keyword": "leather wallet"
}'
```

```python
import requests

url = "https://eto.tools/api/v1/ai/generate-title"
headers = {"X-Eto-API-Key": "eto_your_key"}
payload = {
    "keyword": "leather wallet"
}

response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
print(response.json())
```

```javascript
const url = "https://eto.tools/api/v1/ai/generate-title";
const payload = {
  "keyword": "leather wallet"
};

const response = await fetch(url, {
  method: "POST",
  body: JSON.stringify(payload),
  headers: {
    "X-Eto-API-Key": "eto_your_key",
    "Content-Type": "application/json",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

`application/json`. This endpoint has no worked response example in the registry yet; the [HTML reference](https://eto.tools/dev/docs/#ep-ai-generate-title) shows the fields it returns.

### Errors

Failures answer with the shared error body described in the Errors section: `{"error": {"code", "status", "message", "hint", "docs"}}`. Branch on `code`, not on the message.


## POST /api/v1/ai/generate-description

AI: generate a listing description

- Operation ID: `ai_generate_description`
- Slug: `ai-generate-description`
- Category: AI Studio
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-ai-generate-description
- Markdown: https://eto.tools/dev/docs/ai-studio/ai-generate-description.md

Generate an Etsy listing description. Provide at least one of "keyword" or "title".

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `keyword` | body | `string` | no | Target keyword (keyword or title required) |
| `title` | body | `string` | no | Listing title (keyword or title required) |
| `features` | body | `array` | no | Array of product feature strings |
| `tone` | body | `string` | no | Tone (default "professional") |

### Request

```bash
curl -X POST "https://eto.tools/api/v1/ai/generate-description" \
  -H "X-Eto-API-Key: eto_your_key"
```

```python
import requests

url = "https://eto.tools/api/v1/ai/generate-description"
headers = {"X-Eto-API-Key": "eto_your_key"}

response = requests.post(url, headers=headers, timeout=120)
response.raise_for_status()
print(response.json())
```

```javascript
const url = "https://eto.tools/api/v1/ai/generate-description";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "X-Eto-API-Key": "eto_your_key",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

`application/json`. This endpoint has no worked response example in the registry yet; the [HTML reference](https://eto.tools/dev/docs/#ep-ai-generate-description) shows the fields it returns.

### Errors

Failures answer with the shared error body described in the Errors section: `{"error": {"code", "status", "message", "hint", "docs"}}`. Branch on `code`, not on the message.


## POST /api/v1/ai/generate-image

AI: generate an image (async)

- Operation ID: `ai_generate_image`
- Slug: `ai-generate-image`
- Category: AI Studio
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-ai-generate-image
- Markdown: https://eto.tools/dev/docs/ai-studio/ai-generate-image.md

Start an AI image generation job from a text prompt. Returns a job_id; poll ai_generate_image_status for the result.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `prompt` | body | `string` | yes | Image prompt |

### Request

```bash
curl -X POST "https://eto.tools/api/v1/ai/generate-image" \
  -H "X-Eto-API-Key: eto_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "A leather wallet on a walnut desk, soft daylight"
}'
```

```python
import requests

url = "https://eto.tools/api/v1/ai/generate-image"
headers = {"X-Eto-API-Key": "eto_your_key"}
payload = {
    "prompt": "A leather wallet on a walnut desk, soft daylight"
}

response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
print(response.json())
```

```javascript
const url = "https://eto.tools/api/v1/ai/generate-image";
const payload = {
  "prompt": "A leather wallet on a walnut desk, soft daylight"
};

const response = await fetch(url, {
  method: "POST",
  body: JSON.stringify(payload),
  headers: {
    "X-Eto-API-Key": "eto_your_key",
    "Content-Type": "application/json",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

`application/json`. This endpoint has no worked response example in the registry yet; the [HTML reference](https://eto.tools/dev/docs/#ep-ai-generate-image) shows the fields it returns.

### Errors

Failures answer with the shared error body described in the Errors section: `{"error": {"code", "status", "message", "hint", "docs"}}`. Branch on `code`, not on the message.


## GET /api/v1/ai/generate-image/status

AI: image generation status

- Operation ID: `ai_generate_image_status`
- Slug: `ai-generate-image-status`
- Category: AI Studio
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-ai-generate-image-status
- Markdown: https://eto.tools/dev/docs/ai-studio/ai-generate-image-status.md

Poll the status/result of an AI image generation job.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `job_id` | query | `string` | yes | Job id returned by ai_generate_image |

### Request

```bash
curl -X GET "https://eto.tools/api/v1/ai/generate-image/status?job_id=job_9f2c41d8" \
  -H "X-Eto-API-Key: eto_your_key"
```

```python
import requests

url = "https://eto.tools/api/v1/ai/generate-image/status"
headers = {"X-Eto-API-Key": "eto_your_key"}
params = {
    "job_id": "job_9f2c41d8"
}

response = requests.get(url, headers=headers, params=params, timeout=120)
response.raise_for_status()
print(response.json())
```

```javascript
const url = "https://eto.tools/api/v1/ai/generate-image/status?job_id=job_9f2c41d8";

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-Eto-API-Key": "eto_your_key",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

`application/json`. This endpoint has no worked response example in the registry yet; the [HTML reference](https://eto.tools/dev/docs/#ep-ai-generate-image-status) shows the fields it returns.

### Errors

Failures answer with the shared error body described in the Errors section: `{"error": {"code", "status", "message", "hint", "docs"}}`. Branch on `code`, not on the message.


## POST /api/v1/ai/analyze-image

AI: analyze a product image

- Operation ID: `ai_analyze_image`
- Slug: `ai-analyze-image`
- Category: AI Studio
- Authentication: API key only. Reads or writes data Eto holds for your own account.
- HTML: https://eto.tools/dev/docs/#ep-ai-analyze-image
- Markdown: https://eto.tools/dev/docs/ai-studio/ai-analyze-image.md

Analyze a product image and return a description suitable for an Etsy listing.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `image` | body | `object` | yes | Object with "data" (base64) and "mimeType" (e.g. image/png) |
| `prompt` | body | `string` | no | Optional instruction (default describes the product image) |

### Request

```bash
curl -X POST "https://eto.tools/api/v1/ai/analyze-image" \
  -H "X-Eto-API-Key: eto_your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "image": {}
}'
```

```python
import requests

url = "https://eto.tools/api/v1/ai/analyze-image"
headers = {"X-Eto-API-Key": "eto_your_key"}
payload = {
    "image": {}
}

response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()
print(response.json())
```

```javascript
const url = "https://eto.tools/api/v1/ai/analyze-image";
const payload = {
  "image": {}
};

const response = await fetch(url, {
  method: "POST",
  body: JSON.stringify(payload),
  headers: {
    "X-Eto-API-Key": "eto_your_key",
    "Content-Type": "application/json",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

`application/json`. This endpoint has no worked response example in the registry yet; the [HTML reference](https://eto.tools/dev/docs/#ep-ai-analyze-image) shows the fields it returns.

### Errors

Failures answer with the shared error body described in the Errors section: `{"error": {"code", "status", "message", "hint", "docs"}}`. Branch on `code`, not on the message.