logo
Powered by Redocly

Text

Text routes help you generate, refine, and suggest prompts for image and video workflows.

All routes use application/json.

  • Response → JSON string (the prompt text), not wrapped in {"data": ...}

Endpoints

Method Path Body
POST /v2/text/prompt JSON — optional image_url, image2_url, video_url, prompt, mode, option
POST /v2/text/suggest-prompt No body required
POST /v2/text/refine-prompt JSON — prompt (required)
POST /v2/text/image-2-prompt JSON — image_url (shorthand for Image2Prompt)

Media inputs

Use HTTPS URLs only (no file upload on v2). For video, the API extracts a middle frame and runs the selected option on that frame.

Upload images or video first via POST /v2/image or POST /v2/video if you need hosted URLs.

Authentication

X-Api-Key: YOUR_API_KEY on every request.

Legacy form-data routes (with data wrapper on some responses) remain at /image/*, /video/*, /audio/*, and /text/* (tagged (Legacy) in the schema).

Generate Text Prompt

Generates or transforms prompt text.

Field Notes
option InspireMe (default), Image2Prompt, SuggestPrompt, RefinePrompt
image_url Primary image for vision options
image2_url Optional second image
video_url Uses middle frame when no image_url
prompt Seed text; required for RefinePrompt behavior via option
mode scene, video, image, or audio 
import requests

r = requests.post(
    "https://api.vimmerse.net/v2/text/prompt",
    headers={"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
        "image_url": "https://media.vimmerse.net/example/product.jpg",
        "option": "Image2Prompt",
        "mode": "image",
    },
    timeout=120,
)
r.raise_for_status()
print(r.json())  # JSON string value
SecurityAPIKeyHeader
Request
header Parameters
Authorization (string) or Authorization (null) (Authorization)
Username (string) or Username (null) (Username)
X-Client-Type (string) or X-Client-Type (null) (X-Client-Type)
Request Body schema: application/json
required
image_url
string (Base image URL)
Default: ""
image2_url
string (Second image URL (optional))
Default: ""
video_url
string (Video URL)
Default: ""

Middle frame is extracted and used like an image when no image_url is set.

prompt
string (Prompt)
Default: ""

Seed or instruction text.

mode
string (Mode)
Default: "scene"

Refinement mode.

option
string (Option)
Default: "InspireMe"

Image2Prompt — describe image; SuggestPrompt — creative suggestion; RefinePrompt — improve prompt; InspireMe — auto from inputs.

Responses
200

Generated prompt (JSON string)

400

Bad Request

422

Validation Error

post/v2/text/prompt
Request samples 
Response samples 
application/json
"A cinematic wide shot of a futuristic city at dusk, neon reflections on wet streets, soft volumetric light, ultra-detailed, 8K."
Suggest Text Prompt
Returns a creative prompt suggestion. No request body is required.


import requests

r = requests.post(
    "https://api.vimmerse.net/v2/text/suggest-prompt",
    headers={"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    timeout=60,
)
print(r.json())



SecurityAPIKeyHeader 
Request 
header Parameters
Authorization (string) or Authorization (null) (Authorization) 
 
Username (string) or Username (null) (Username) 
 
X-Client-Type (string) or X-Client-Type (null) (X-Client-Type) 
 
Responses 
200
Suggested prompt (JSON string)


400
Bad Request


422
Validation Error


post/v2/text/suggest-prompt
Request samples 
Response samples 
application/json
"A cinematic wide shot of a futuristic city at dusk, neon reflections on wet streets, soft volumetric light, ultra-detailed, 8K."
Image to Prompt
Describes image_url in one prompt (same as POST /v2/text/prompt with "option": "Image2Prompt").


import requests

r = requests.post(
    "https://api.vimmerse.net/v2/text/image-2-prompt",
    headers={"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={"image_url": "https://media.vimmerse.net/example/photo.jpg"},
    timeout=120,
)
print(r.json())



SecurityAPIKeyHeader 
Request 
header Parameters
Authorization (string) or Authorization (null) (Authorization) 
 
Username (string) or Username (null) (Username) 
 
X-Client-Type (string) or X-Client-Type (null) (X-Client-Type) 
 
Request Body schema: application/json
required
image_url
required
string (Image URL)   non-empty 
 
Responses 
200
Generated prompt (JSON string)


400
Bad Request


422
Validation Error


post/v2/text/image-2-prompt
Request samples 
Response samples 
application/json
"A cinematic wide shot of a futuristic city at dusk, neon reflections on wet streets, soft volumetric light, ultra-detailed, 8K."
Refine Text Prompt
Improves the supplied prompt for image/video generation.


import requests

r = requests.post(
    "https://api.vimmerse.net/v2/text/refine-prompt",
    headers={"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={"prompt": "Nike shoes on colorful background"},
    timeout=60,
)
print(r.json())



SecurityAPIKeyHeader 
Request 
header Parameters
Authorization (string) or Authorization (null) (Authorization) 
 
Username (string) or Username (null) (Username) 
 
X-Client-Type (string) or X-Client-Type (null) (X-Client-Type) 
 
Request Body schema: application/json
required
prompt
required
string (Prompt)   non-empty 
Prompt to refine.


 
Responses 
200
Refined prompt (JSON string)


400
Bad Request


422
Validation Error


post/v2/text/refine-prompt
Request samples 
Response samples 
application/json
"A cinematic wide shot of a futuristic city at dusk, neon reflections on wet streets, soft volumetric light, ultra-detailed, 8K."
➔ Next to Video