Soul 2

Soul 2 API by Higgsfield. Photoreal portrait, fashion and editorial AI images with styles, from $0.01 per image.

POST/v1/media/queue

from $0.01/image

Overview

Soul 2 by Higgsfield — photoreal portrait, fashion and editorial images with selectable styles. At $0.01 per 720p image it is the lowest-cost image model on YepAPI. Async operation — submit a job, poll for completion.

Property	Value
Model ID	`higgsfield/soul-2`
Alias	`soul-2`
Provider	Higgsfield
Category	Image Generation
Inputs	text-to-image, image reference
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.01/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-2',
    prompt: 'Editorial portrait of a woman in a camel trench coat on a rainy Paris street, 35mm film look',
    options: {
      aspectRatio: '1:1',
      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-2", "prompt": "Editorial portrait of a woman in a camel trench coat on a rainy Paris street, 35mm film look", "options": {"aspectRatio": "1:1", "resolution": "720p", "params": {"seed": 1234, "style_strength": 0.8}}}'

With a Reference Image

Pass a reference image via imageData alongside your prompt.

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-2',
    prompt: 'Same person, now in a tailored navy suit at a rooftop bar at dusk',
    options: {
      resolution: '720p',
    },
    imageData: {
      mimeType: 'image/png',
      base64: '...', // Base64-encoded image
    },
  }),
});

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-2", "prompt": "Same person, now in a tailored navy suit at a rooftop bar at dusk", "options": {"resolution": "720p"}, "imageData": {"mimeType": "image/png", "base64": "..."}}'

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-2` or alias `soul-2`	—
`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 (text-to-image only)	`1:1`
`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	—
`imageData.mimeType`	`string`	No	MIME type of input image (image/png, image/jpeg, image/webp)	—
`imageData.base64`	`string`	No	Base64-encoded reference image	—

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) (only text-to-image)	—
`custom_reference_strength`	`number`	0–1	How strongly to apply the custom reference (only text-to-image)	`1.0`
`enhance_prompt`	`boolean`	—	Expand the prompt before generating (only text-to-image)	`false`
`seed`	`integer`	1–1000000	Random seed for reproducible results (only text-to-image)	—
`style_id`	`string`	—	Style preset (UUID) (only text-to-image)	`3db34ab5-3439-4317-9e03-08dc30852e69`
`style_strength`	`number`	0–1	How strongly to apply the style (only text-to-image)	`1.0`

Features

Photoreal portraits, fashion and editorial shots
Styles via options.params.style_id / style_strength
720p or 1080p, seven aspect ratios
Optional reference image via imageData

Pricing

Resolution	Cost per image
720p	$0.01
1080p	$0.02

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

Soul 2

On this page