# Formats API

Create a format from a link, read and list formats, start a step that waited for funds, and delete a format with all made from it.

## Create a format

`POST /api/v1/formats`

Reads the site, writes the Format DNA and makes a video in each style asked for, by itself. Needs **Formats: Write**.

| Field | Needed | What it is |
|---|---|---|
| `link` | required | The site, or the App Store or Google Play page, to make ads for. |
| `styles` | optional | Style ids from the [Styles API](/docs/api/reference/styles), at most 10. A video is made in each. None: one video in the site's own look. |
| `aspects` | optional | Any of `"9:16"`, `"1:1"`, `"16:9"`. Each video is made in each shape. Default `["9:16"]`. |
| `length` | optional | Seconds, from 5 to 30. Default 20. A video is [priced](/docs/api/pricing) by its length. |
| `voiceover` | optional | `true` for a narrated video. Default `false`. |
| `music` | optional | `false` for videos with no music, with `"engine": "motion-v1-flash"` only: Motion V1 always makes music. Default `true`. Music is [priced](/docs/api/pricing) on its own. |
| `goal` | optional | One of `installs`, `signups`, `sales`, `leads`, `awareness`. |
| `audience` | optional | Who the ads are for, in a sentence. |
| `angle` | optional | The one idea the ads are built on, in a sentence. |
| `notes` | optional | Anything else the writers should know. |
| `name` | optional | The product's name. Read from the site when left out. |
| `videos` | optional | `false` to only read the site and write the Format DNA. Default `true`. |
| `count` | optional | How many videos it makes by itself of each style, or of the site's own look, from 1 to 6. Default 1. |
| `engine` | optional | `"motion-v1"` or `"motion-v1-flash"` for the videos it makes by itself. Default `"motion-v1"`. [Motion V1 Flash](/docs/models) makes videos only, at its own price. |
| `reuse` | optional | A site you read before is not read again, and not paid for again. `false` reads it again. |

The whole of it is checked against what can pay before anything starts. When it cannot be paid, the answer is `402` with `"code": "funds"` and nothing is made.

cURL:

```bash
curl https://10xvid.com/api/v1/formats \
  -H "Authorization: Bearer $TENX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"link": "https://typally.com", "styles": ["whiteboard", "clay"], "aspects": ["9:16", "1:1"], "length": 15}'
```

JavaScript:

```js
const res = await fetch('https://10xvid.com/api/v1/formats', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.TENX_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ link: 'https://typally.com', styles: ['whiteboard', 'clay'], aspects: ['9:16', '1:1'], length: 15 }),
});
const format = await res.json();
```

Python:

```python
res = requests.post(
    "https://10xvid.com/api/v1/formats",
    headers={"Authorization": f"Bearer {os.environ['TENX_API_KEY']}"},
    json={"link": "https://typally.com", "styles": ["whiteboard", "clay"], "aspects": ["9:16", "1:1"], "length": 15},
)
format = res.json()
```

The answer is `201` with the format:

```json
{
  "id": "typally-com-mgn4x2a1",
  "object": "format",
  "name": "Typally",
  "link": "https://typally.com/",
  "status": "reading",
  "error": null,
  "styles": ["whiteboard", "clay"],
  "aspects": ["9:16", "1:1"],
  "engine": "motion-v1",
  "voiceover": false,
  "music": true,
  "length": 15,
  "videos_expected": 2,
  "created": "2026-10-13T09:12:04.551Z"
}
```

## The format object

| Field | What it is |
|---|---|
| `id` | The format's id. |
| `object` | Always `format`. |
| `name` | The product's name, as read from the site or sent. |
| `link` | The link it was made from. |
| `status` | `reading`, `writing`, `ready`, `waiting` or `failed`. See below. |
| `error` | What went wrong, in a sentence, when `status` is `failed` or `waiting`. |
| `styles` | The styles asked for. |
| `aspects` | The shapes its videos are made in. |
| `engine` | The engine its videos are made with: `motion-v1` or `motion-v1-flash`. |
| `voiceover` | Whether its videos are narrated. |
| `music` | Whether its videos have music. |
| `length` | The length of its videos in seconds, or `null` when none was asked: then they are 20 seconds. |
| `videos_expected` | How many videos it makes by itself: `count` in each style, `count` with none, or 0 when asked for none. |
| `created` | When it was made. |
| `videos` | Its videos, newest first. Only in `GET /formats/{id}`. |

| Status | What it means |
|---|---|
| `reading` | The site is being read. |
| `writing` | The Format DNA is being written. |
| `ready` | Videos can be made from it. The ones asked for start by themselves, each once its style is written. |
| `waiting` | A step could not be paid for when it was due. Add funds and it carries on by itself, or call `continue`. |
| `failed` | The site could not be read, or the Format DNA could not be written. What it cost was given back. |

## Get a format

`GET /api/v1/formats/{id}`

The format with its `videos`. Needs **Formats: Read**.

## List formats

`GET /api/v1/formats`

Your formats, newest first. Needs **Formats: Read**.

| Query | What it is |
|---|---|
| `limit` | How many, from 1 to 100. Default 20. |
| `before` | Only formats made before this moment, as an ISO date or milliseconds. Use the last one's `created` for the next page. |

```json
{
  "object": "list",
  "data": [
    { "id": "typally-com-mgn4x2a1", "object": "format", "status": "ready" }
  ],
  "has_more": false
}
```

## Continue a format

`POST /api/v1/formats/{id}/continue`

Starts the step that waited for funds, once they are there. A format that waits nothing is answered as it is. Needs **Formats: Write**.

## Delete a format

`DELETE /api/v1/formats/{id}`

Stops its work and deletes it, with its styles, its videos and its images. It cannot be undone. Needs **Formats: Write**.

```json
{ "id": "typally-com-mgn4x2a1", "object": "format", "deleted": true }
```