Generate Avatar Images

Generate new images to an existing avatar profile with the given avatar_id using AI.

Generate Avatar Images API Documentation

The POST /v1/avatar-profiles/{avatar_id}/images/generate lets you add new AI images to your existing avatar profile. The default model used for image generation is google/nano-banana-2 but you can change it using the model field in the body of the POST request.

API Request

The API endpoint handles the task asynchronously using a fast queue-based system, and the request immediately returns a request_id. Use the request_id to poll the status of the generation and return the result after the task is completed.

Sending Request

bash
curl -X POST "https://api.zoice.com/v1/avatar-profiles/b92d8dd4-f3fa-4624.../images/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ZOICE_API_KEY" \
  -d '{
    "model": "openai/gpt-image-2.5-flare",
    "base_image_id": "img_2233a5...",
	"reference_image_urls": [
      "https://storage.zoice.com/api/assets/image-ddc61733-0ed9-...png"
    ],
	"image_prompt": "replace the outfit.",
	"aspect_ratio": "9:16",
	"resolution": "2k",
	"num_images": 1
}'

Response Format

json
{
  "request_id": 'd1f47b9c-6387-49d0-a403-...',
  "status": 'processing',
}

Polling and Output

After submitting an asynchronous API request, you can use the request_id obtained from the response to further poll for the status of the generation and ultimately retrieve the result after the completion. Use the /v1/fetch/request_id endpoint to perform this operation.

Polling Request

bash
curl -X GET "https://api.zoice.com/v1/fetch/{request_id}" \
  -H "Authorization: Bearer $ZOICE_API_KEY"

Polling Response

json
{
  "status": "success",
  "type": "avatar_images",
  "credits_used": 100,
  "output": [
    {
      "image_id": "img_hOUj...",
      "is_ai": true,
      "generation_info": {
        "model": "openai/gpt-image-2.5-flare",
        "image_prompt": "replace the outfit.",
        "resolution": "2k",
        "aspect_ratio": "9:16",
        "base_image_id": "img_2233a5...",
        "reference_image_urls": [
          "https://storage.zoice.com/api/assets/image-ddc61733-0ed9-...png"
        ]
      },
      "image_url": "https://storage.zoice.com/api/assets/image-fec81743-2fc9-...png",
      "created_at": "2026-10-02T05:31:33.537Z"
    }
  ]
}