# Create a cast member

`POST https://api.vidmoat.com/v1/cast`

- Scope: `cast.write`
- Cost: Free

Save a member from 1 to 8 images in the account: uploads (`referenceUrls`), a generated image (`fromUrl`), or a frame of a video (`fromJobId`, or `fromFrame` `{ src, time }`; without a time the sharpest last frame). Characters get a face print for the consistency check.

### Body

- `name` (string, required): Up to 60 characters.
- `kind` (enum, optional, default `character`): What it is. One of `character`, `location`, `prop`, `style`.
- `description` (string, optional): The words that must never drift, appended to every prompt that uses the member. Up to 600 characters; longer is refused, never truncated.
- `referenceUrls` (array of strings, optional): Images in the account, 1 to 8.
- `views` (array of enums, optional): One per reference: front, three_quarter, profile, back, full_body, expression, wide or detail.
- `fromUrl` (string, optional): A generated image in the account.
- `fromJobId` (string, optional): A finished video generation; its frame becomes the reference.
- `voiceId` (string, optional): A Speech Lab voice of the account or a published one, or a stock voice with `voiceProvider`.

## Response

Returns `201`.

### Response fields

- `member` (object): The member.
- `problems` (array): For example: no face found, so the face check reports this member as unknown.

## Errors

Besides the errors any request can get ([authentication](https://developer.vidmoat.com/developer/docs/authentication#when-a-request-is-refused), [rate limits](https://developer.vidmoat.com/developer/docs/rate-limits)):

| Status | Code | When |
| --- | --- | --- |
| 400 | [`invalid_request`](https://developer.vidmoat.com/developer/docs/errors#invalid_request) | A missing name, an image not in the account, more than 8 images, a description over 600 characters, or a real person. |

## Request examples

```bash curl
curl -X POST https://api.vidmoat.com/v1/cast \
  -H "Authorization: Bearer $VIDMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"character","name":"Mara","referenceUrls":["/uploads/mara-front.png"]}'
```

```js Node
const res = await fetch('https://api.vidmoat.com/v1/cast', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIDMOAT_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    kind: 'character',
    name: 'Mara',
    referenceUrls: [
      '/uploads/mara-front.png',
    ],
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error?.message ?? `HTTP ${res.status}`);
console.log(data);
```

```python Python
import os
import requests

res = requests.post(
    "https://api.vidmoat.com/v1/cast",
    headers={"Authorization": f"Bearer {os.environ['VIDMOAT_KEY']}"},
    json={
      "kind": "character",
      "name": "Mara",
      "referenceUrls": [
        "/uploads/mara-front.png",
      ],
    },
    timeout=60,
)
res.raise_for_status()
print(res.json())
```

## Example response

```json
{ "member": {
  "id": "cm_5f2a9c1d7e3b",
  "kind": "character",
  "name": "Mara",
  "description": "white spiky hair, black mask, red scarf, number 7 on the chest",
  "references": [{ "id": "cr_81b2", "url": "https://api.vidmoat.com/uploads/mara-front.png", "view": "front", "source": "upload", "approved": true, "hasFace": true }],
  "identity": { "method": "sface-2021dec", "ceiling": null, "refs": 1 }
}, "problems": [] }
```

---

Source: https://developer.vidmoat.com/developer/docs/api/cast/create-cast-member
Previous: [List the Cast](https://developer.vidmoat.com/developer/docs/api/cast/list-cast.md)
Next: [Get a cast member](https://developer.vidmoat.com/developer/docs/api/cast/get-cast-member.md)
All documentation: https://developer.vidmoat.com/llms-full.txt