Soul

Soul API by Higgsfield. The original Soul photoreal image model, with styles and seeds.

POST/v1/media/queue

from $0.19/image

Overview

Soul by Higgsfield — the original Soul photoreal image model, with selectable styles. Async operation — submit a job, poll for completion.

Property	Value
Model ID	`higgsfield/soul`
Alias	`soul`
Provider	Higgsfield
Category	Image Generation
Inputs	text-to-image
Resolutions	720p, 1080p
Aspect Ratios	9:16, 16:9, 4:3, 3:4, 1:1, 2:3, 3:2
Billing	Per job — priced when queued, charged only on success
Pricing	from $0.19/image

Usage

All media models use the async job queue. Submit a job, then poll for the result.

Step 1: Submit Job

Text-to-Image

options.params passes this model's own parameters (see Model parameters).

const res = await fetch('https://api.yepapi.com/v1/media/queue', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'higgsfield/soul',
    prompt: 'Street-style photo of a man in a vintage leather jacket, golden hour, shallow depth of field',
    options: {
      aspectRatio: '4:3',
      resolution: '720p',
      params: {
        seed: 1234,
        style_strength: 0.8,
      },
    },
  }),
});
const { data } = await res.json();
// data.jobId — use this to poll for results

curl -X POST https://api.yepapi.com/v1/media/queue \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "higgsfield/soul", "prompt": "Street-style photo of a man in a vintage leather jacket, golden hour, shallow depth of field", "options": {"aspectRatio": "4:3", "resolution": "720p", "params": {"seed": 1234, "style_strength": 0.8}}}'

Step 2: Poll for Result

const status = await fetch(`https://api.yepapi.com/v1/media/status/${data.jobId}`, {
  headers: { 'x-api-key': 'YOUR_API_KEY' },
});
const { data: job } = await status.json();
// job.status — "pending" | "processing" | "completed" | "failed"
// job.result.image — { mimeType, base64 } when completed

curl https://api.yepapi.com/v1/media/status/JOB_ID \
  -H "x-api-key: YOUR_API_KEY"

Request Body

Parameter	Type	Required	Description	Default
`model`	`string`	Yes	`higgsfield/soul` or alias `soul`	—
`prompt`	`string`	Yes	Text description of the image to generate	—
`options.aspectRatio`	`string`	No	One of: 9:16, 16:9, 4:3, 3:4, 1:1, 2:3, 3:2	`4:3`
`options.resolution`	`string`	No	`720p`, `1080p`	`720p`
`options.params`	`object`	No	Model-specific parameters under their own names: `custom_reference_id`, `custom_reference_strength`, `enhance_prompt`, `seed`, `style_id`, `style_strength`. Unknown names return 400	—

Options are validated when you submit: an unsupported duration, resolution or value returns 400 naming the allowed values.

Model parameters

Pass these inside options.params.

Parameter	Type	Allowed	Description	Default
`custom_reference_id`	`string`	—	ID of a saved custom character reference (UUID)	—
`custom_reference_strength`	`number`	0–1	How strongly to apply the custom reference	`1.0`
`enhance_prompt`	`boolean`	—	Expand the prompt before generating	`false`
`seed`	`integer`	1–1000000	Random seed for reproducible results	—
`style_id`	`string`	—	Style preset (UUID)	`464ea177-8d40-4940-8d9d-b438bab269c7`
`style_strength`	`number`	0–1	How strongly to apply the style	`1.0`

Features

Photoreal portrait and lifestyle images
Styles via options.params.style_id / style_strength
720p or 1080p, seven aspect ratios

Pricing

Resolution	Cost per image
720p	$0.19
1080p	$0.38

One image per job. Each job is priced when it's queued and charged only if it succeeds — failed or moderated jobs are free.

Info

Image jobs typically complete in 5–60 seconds. Results retained for 1 hour.

Under the Hood

On this page