# Write captions

> Write captions with the Wavegrain Posting API: POST /api/v1/captions. Request body, responses and an example request.

> Index of these docs: https://wavegrain.com/developers/llms.txt

`POST /api/v1/captions` is part of the [Posting API](/developers/posting-api). Every call needs an access key: see [Authentication](/developers/authentication).

Needs the `generate` permission.

One caption per network you name, from a topic, your own text, or both, in your brand's voice (`brandId`, or your active brand). Each caption fits that network's length limit, and Instagram's hashtag limit.

Costs 1 credit per request, counted against the access key's daily credit limit, at most 200 requests in any 24 hours per account; a request that fails is refunded. Nothing is posted: use the captions in POST /api/v1/posts.

## Request body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `topic` | string | no | What the post is about. |
| `text` | string | no | Your own text to turn into captions, such as a draft or the words on your images. |
| `networks` | "tiktok" \| "instagram" \| "facebook" \| "threads" \| "youtube" \| "linkedin" \| "pinterest"[] | yes | The networks to write a caption for. |
| `brandId` | string | no | Write in this brand's voice; one of your brands from GET /api/v1/accounts. |
| `emoji` | "none" \| "auto" \| "expressive" | no | none, auto or expressive. |

## Example request

```bash
curl -X POST https://wavegrain.com/api/v1/captions \
  -H "Authorization: Bearer $WAVEGRAIN_KEY" -H "Content-Type: application/json" \
  -d '{"topic":"Three ways to keep rice fluffy","networks":["instagram","threads"],"emoji":"auto"}'
```

## Responses

| Status | Meaning |
| --- | --- |
| 200 | One caption per network. |
| 400 | The body is not valid; `details` names the field. |
| 401 | No access key, or an unknown, revoked or expired one |
| 402 | Not enough credits. |
| 403 | The key lacks the permission or was revoked during the request, the account has no active plan, or its credits are on hold (`credits_on_hold`). |
| 404 | No such brand of yours. |
| 429 | Too many requests for the key or the account, the key's or the account's daily credit limit, or 200 captions in 24 hours. |
| 500 | Something went wrong on Wavegrain's side; try again, and send the request id if it keeps failing. |
| 503 | The captions could not be written; nothing was charged. |

A successful answer:

```json
{
  "captions": {
    "instagram": "Three ways to keep rice fluffy, every time. Which one do you use? #ricetips #cooking",
    "threads": "Three ways to keep rice fluffy. Number two changed my week."
  },
  "creditsCharged": 1
}
```

## More in the Posting API

- [List brands, groups and connected accounts](/developers/api/list-accounts): `GET /api/v1/accounts`
- [List posts](/developers/api/list-posts): `GET /api/v1/posts`
- [Create a post](/developers/api/create-post): `POST /api/v1/posts`
- [Get a post](/developers/api/get-post): `GET /api/v1/posts/{id}`
- [Cancel a post](/developers/api/cancel-post): `DELETE /api/v1/posts/{id}`
- [Start an image or video upload](/developers/api/create-upload): `POST /api/v1/media`
- [Get an upload](/developers/api/get-upload): `GET /api/v1/media/{id}`
- [Delete a video](/developers/api/delete-video): `DELETE /api/v1/media/{id}`
- [Finish and check a video upload](/developers/api/complete-video-upload): `POST /api/v1/media/{id}/complete`
- [All endpoints](/developers/api)
