---
title: "Generate shorts avatar"
method: POST
path: "/api/agent/shorts/avatar"
tags: ["Shorts"]
---

# Generate shorts avatar

`POST /api/agent/shorts/avatar`

## Request body

- ShortsAvatarRequest
  - `gender` 'male' | 'female', required
  - `origin` 'european' | 'asian' | 'african' | 'latin' | 'middle_eastern' | 'south_asian', required
  - `age_range` '18-25' | '26-35' | '36-50'
  - `type` 'tech_founder' | 'vibe_coder' | 'student' | 'executive'
  - `location` 'coffee_shop' | 'dev_cave' | 'street' | 'car' | 'home_office' | 'podcast_studio' | 'glass_office' | 'rooftop' | 'bedroom' | 'park' | 'gym'

## Response `200`

Avatar generated

- ShortsAvatarResponse
  - `avatar_url` string, uri, required
  - `r2_key` string, required
  - `credits_charged` integer, required
  - `prompt_used` string, required — Full image prompt used for this generation (same input params can yield different prompts for diversity).
  - `prompt_meta` ShortsAvatarPromptMeta, required
    - `age_years` integer, required
    - `variation_tags` string[], required — Server-sampled appearance and location tags for debugging and diversity checks.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `402` — Insufficient credits
- `429` — Rate limit exceeded
- `500` — Internal server error

## Changes

- **2026-05-02** `9bdc49d3a3c7` — 2 info
  - the response property `prompt_meta` became required for the status `200`
  - the response property `prompt_used` became required for the status `200`
- **2026-04-24** `8970b7d68e49` — 2 info
  - added the optional property `prompt_meta` to the response with the `200` status
  - added the optional property `prompt_used` to the response with the `200` status
- **2026-03-03** `9cd5ce117b1d` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/citedy/apis/citedy-agent-api/changes/api/agent/shorts/avatar/post.md)

---

[API](https://skmtc.dev/citedy/apis/citedy-agent-api.md) · [All operations](https://skmtc.dev/citedy/apis/citedy-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/citedy/citedy-agent-api/revisions/b5785d3fe446/schema)