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

# POST /jobs/[id]/artist-link

> Give one of your artists their own link to order and make a lyric video

## Endpoint

```
POST https://lyrcs.ai/api/v1/jobs/{job_id}/artist-link
```

Returns a link that opens **one artist's own songs** on lyrcs.ai. There they can
order a lyric video, style it, render it and download it. The artist needs no
lyrcs.ai account, and you never share a login: the link is the artist's access,
scoped to the songs you have attached to them.

Call it when the artist clicks "make a video" in your product, and send them to
the `url` it returns. Each call issues a fresh link.

> [!NOTE]
>
> `studio_url` on [`GET /jobs/{id}`](https://docs.lyrcs.ai/api-reference/jobs) is for your own team's
> signed-in lyrcs.ai accounts. Artists cannot open it. Send artists the `url` from
> this endpoint instead.

## Request

```bash theme={null}
curl -X POST https://lyrcs.ai/api/v1/jobs/{job_id}/artist-link \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "end_user": { "external_id": "artist-123", "name": "Asha", "email": "asha@example.com" }
  }'
```

| Field | Type | Notes |
| - | - | - |
| `end_user` | `object` | Which of your artists this song belongs to. Optional when the job was submitted with an `end_user`. |
| `end_user.external_id` | `string` | **Required** inside `end_user`. Your own id for the artist, up to 128 characters. |
| `end_user.name` | `string` | Optional. |
| `end_user.email` | `string` | Optional. Used for order receipts and "video ready" emails. |

### Which artist the link is for

| The job… | You send… | Result |
| - | - | - |
| already has an `end_user` | nothing, or the same `external_id` | Link for that artist |
| has no `end_user` | an `end_user` | The artist is attached to the job, then the link is issued |
| has no `end_user` | nothing | `422 ART_001` |
| belongs to a different `end_user` | another `external_id` | `409 ART_002` — a song never moves between artists |

The link opens **every** song attached to that artist, not only this one. Use
the same `external_id` for the same artist across all of their songs.

## Response

`201 Created`

```json theme={null}
{
  "job_id": "a1b2c3d4-…",
  "url": "https://lyrcs.ai/artist?token=ps_…",
  "expires_at": "2026-12-17T10:00:00.000Z",
  "end_user": { "external_id": "artist-123" },
  "video": { "available": true, "payment": "prepaid" }
}
```

| Field | Notes |
| - | - |
| `url` | Send the artist here. Treat it as a secret: anyone holding it can act as that artist. |
| `expires_at` | 30 days from issue. The expiry extends while the artist keeps using the link. Ask for a new one any time. |
| `video.available` | Whether the artist can order a video for this song right now. |
| `video.payment` | `prepaid` — your account's video credits pay and the artist sees no price. `pay_on_site` — the artist pays at checkout. `null` when video is not enabled. |
| `video.reason` | Present when `available` is `false`, see below. |

### When `video.available` is false

The link is still issued. The artist can view their lyrics and downloads there.

| `reason` | Meaning |
| - | - |
| `not_enabled` | Lyric videos are not enabled on your account. Contact us. |
| `no_credits` | Your prepaid video credits are used up. Contact us to top up. |
| `lyrics_not_ready` | The song is still being transcribed, timed or reviewed. The page shows progress, and the order button appears once lyrics are timed. |
| `not_aligned` | The job was submitted as transcript-only, so it has no timings and never will on its own. Call [`POST /jobs/{id}/align`](https://docs.lyrcs.ai/api-reference/align-job) first. |

## Errors

| Status | Code | Meaning |
| - | - | - |
| `400` | `VAL_001` | `end_user` is malformed — for example, no `external_id`. |
| `401` | `AUTH_001` | Missing or invalid API key. |
| `404` | `NOT_001` | No such job on your account. |
| `409` | `ART_002` | The job belongs to a different `end_user`. |
| `409` | `ART_003` | The job failed. Resubmit the song. |
| `422` | `ART_001` | The job has no `end_user` and you did not send one. |
| `429` | `RATE_001` | Rate limit. Counts against the read limit, not submissions. |

This endpoint never charges you. Charges happen only when the artist places an order.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.