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

# Discovery

> Browse available models and voices, estimate costs, and discover existing projects.

## List models

<br />

```
GET /models
```

Returns all available generation models with their capabilities and supported features.

| Parameter | Type   | Description                   |
| --------- | ------ | ----------------------------- |
| `type`    | string | Filter by `video` or `image`. |

### Response `200`

```json theme={"dark"}
{
  "models": [
    {
      "id": "kling-3.0",
      "name": "Kling 3.0",
      "type": "video",
      "generation_types": ["text-to-video", "image-to-video"],
      "aspect_ratios": ["16:9", "9:16", "1:1"],
      "durations": ["4s", "6s", "8s"],
      "resolutions": ["1080p"],
      "has_sound": true,
      "supports_audio_toggle": true,
      "supports_audio_input": false,
      "supports_image_input": true,
      "supports_end_frame": false,
      "supports_multi_shot": false,
      "supports_reference_images": false,
      "max_reference_images": null,
      "supports_reference_videos": false,
      "max_reference_videos": null,
      "supports_video_input": false,
      "max_input_video_duration": null,
      "supports_negative_prompt": true,
      "supports_camera_fixed": false,
      "supports_camera_motion": true,
      "camera_motion_options": ["static", "dolly_in", "dolly_out", "tracking_left", "tracking_right"],
      "max_prompt_length": 2500
    }
  ]
}
```

Use model IDs when setting project defaults (`video_model`, `image_model`) or when directing the agent to use a specific model.

## List voices

<br />

```
GET /voices
```

Returns available voiceover voices with descriptions.

| Parameter | Type   | Description                               |
| --------- | ------ | ----------------------------------------- |
| `gender`  | string | Filter by `male`, `female`, or `neutral`. |

### Response `200`

```json theme={"dark"}
{
  "voices": [
    {
      "name": "Isabella",
      "gender": "female",
      "age": "young adult",
      "accent": "American",
      "style": "warm, conversational",
      "description": "Warm and engaging, ideal for lifestyle brands and conversational narration."
    },
    {
      "name": "James",
      "gender": "male",
      "age": "middle-aged",
      "accent": "British",
      "style": "authoritative, cinematic",
      "description": "Deep and commanding, suited for luxury brands and cinematic narration."
    }
  ]
}
```

Voice names can be used when directing the agent: `"Use the voice Isabella for the voiceover"`.

## Estimate costs

<br />

```
POST /estimate-cost
```

Estimate credit costs for planned operations before committing.

### Request body

| Parameter    | Type  | Required | Description                         |
| ------------ | ----- | -------- | ----------------------------------- |
| `operations` | array | Yes      | List of planned operations. Max 50. |

Each operation:

| Field         | Type    | Required | Description                                                                                                                    |
| ------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `tool`        | string  | Yes      | `generate_image`, `generate_video`, `generate_audio`, `upscale_media`, `analyze_media`, `remove_background`, `motion_overlay`. |
| `model`       | string  | Varies   | Required for `generate_image` and `generate_video`.                                                                            |
| `type`        | string  | Varies   | Required for `generate_audio` (`voiceover`, `music`, `sound_effect`) and `upscale_media` (`image`, `video`).                   |
| `duration`    | number  | Varies   | Required for `generate_video` (seconds).                                                                                       |
| `count`       | integer | No       | Number of generations. Default 1, max 100.                                                                                     |
| `sound`       | boolean | No       | Include audio in video generation.                                                                                             |
| `resolution`  | string  | No       | Output resolution.                                                                                                             |
| `music_model` | string  | No       | Music engine for audio generation.                                                                                             |

### Response `200`

```json theme={"dark"}
{
  "items": [
    {
      "operation": "generate_video",
      "credits_per_unit": 55,
      "count": 4,
      "subtotal": 220
    },
    {
      "operation": "generate_image",
      "credits_per_unit": 12,
      "count": 4,
      "subtotal": 48
    }
  ],
  "total_credits": 268,
  "is_partial": false,
  "note": "Covers generation costs only. Agent reasoning costs are additional."
}
```

### Example

<CodeGroup>
  ```bash curl theme={"dark"}
  curl -X POST https://eversince.ai/api/v1/estimate-cost \
    -H "Authorization: Bearer $EVERSINCE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "operations": [
        { "tool": "generate_video", "model": "seedance-2.0", "duration": 5, "count": 4 },
        { "tool": "generate_image", "model": "nano-banana-pro", "count": 4 },
        { "tool": "generate_audio", "type": "voiceover", "duration": 15 },
        { "tool": "generate_audio", "type": "music", "duration": 15 }
      ]
    }'
  ```

  ```python Python theme={"dark"}
  estimate = requests.post(f"{BASE}/estimate-cost", headers=headers, json={
      "operations": [
          {"tool": "generate_video", "model": "seedance-2.0", "duration": 5, "count": 4},
          {"tool": "generate_image", "model": "nano-banana-pro", "count": 4},
          {"tool": "generate_audio", "type": "voiceover", "duration": 15},
          {"tool": "generate_audio", "type": "music", "duration": 15}
      ]
  }).json()

  print(f"Estimated cost: {estimate['total_credits']} credits")
  ```

  ```javascript JavaScript theme={"dark"}
  const estimate = await fetch(`${BASE}/estimate-cost`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      operations: [
        { tool: "generate_video", model: "seedance-2.0", duration: 5, count: 4 },
        { tool: "generate_image", model: "nano-banana-pro", count: 4 },
        { tool: "generate_audio", type: "voiceover", duration: 15 },
        { tool: "generate_audio", type: "music", duration: 15 },
      ],
    }),
  }).then((r) => r.json());

  console.log(`Estimated cost: ${estimate.total_credits} credits`);
  ```
</CodeGroup>

## Discover existing projects

<br />

```
GET /projects/discover
```

List projects created in the studio that are available for API management.

| Parameter | Type    | Default | Description              |
| --------- | ------- | ------- | ------------------------ |
| `limit`   | integer | 20      | Results per page. 1–100. |
| `offset`  | integer | 0       | Pagination offset.       |
| `title`   | string  |         | Search by title.         |

### Response `200`

The `title` field can be `null` if the project has no title set.

```json theme={"dark"}
{
  "projects": [
    {
      "project_id": "proj_abc123",
      "title": "My Project",
      "aspect_ratio": "16:9",
      "project_url": "https://eversince.ai/app/projects/...",
      "created_at": "2025-03-15T10:30:00Z",
      "updated_at": "2025-03-15T10:35:00Z"
    }
  ],
  "total": 5,
  "limit": 20,
  "offset": 0
}
```

## Adopt a project

<br />

```
POST /projects/adopt
```

Take control of an existing studio project via the API.

### Request body

| Parameter    | Type   | Required | Description                                |
| ------------ | ------ | -------- | ------------------------------------------ |
| `project_id` | string | Yes      | The project ID from discovery.             |
| `mode`       | string | No       | `autonomous` or `collaborative` (default). |

### Response `201` (newly adopted)

```json theme={"dark"}
{
  "id": "proj_abc123",
  "status": "idle",
  "mode": "collaborative",
  "project_url": "https://eversince.ai/app/projects/..."
}
```

### Response `200` (already adopted)

If the project was already adopted, returns the existing record with a `message` field.

```json theme={"dark"}
{
  "id": "proj_abc123",
  "status": "idle",
  "mode": "collaborative",
  "project_url": "https://eversince.ai/app/projects/...",
  "message": "Project already adopted"
}
```

After adoption, all project endpoints work normally. The project remains accessible in the studio.