Image Generation Placeholders

Generating an image can take a while. Instead of leaving the chat silent, your YoAI can send a placeholder right away. YoPhone shows it as a loader, and your YoAI then edits it into the finished image or marks it as failed.

The generation object

Add generation to a sendMessage or editMessage request:

{
    "kind": "image",
    "status": "pending",
    "aspectRatio": 1.5
}

• kind (required):
  What is being generated. Only image is supported.

• status (required):
  pending while the image is being generated, shown as a loader. failed if generation did not succeed.

• aspectRatio (optional):
  Width divided by height of the expected image, for example 1 for a square or 1.5 for 3:2. YoPhone uses it to size the loader. Must be greater than 0.

In a JSON request, send generation as an object. In a multipart/form-data request, send it as a JSON string in a generation form field.

Flow

1. Send the placeholder

curl -X POST https://yoai.yophone.com/api/pub/sendMessage \
-H "Content-Type: application/json" \
-H "X-YoAI-API-Key: your YoAI api token" \
-d '{
  "to": "123456789",
  "text": "Generating your image...",
  "generation": { "kind": "image", "status": "pending", "aspectRatio": 1 }
}'

Store the messageId from the response:

{
    "success": true,
    "code": 200,
    "data": {
        "messageId": "6f1d2c3e-8f00-11ef-8000-000000000001"
    }
}

2a. Replace the placeholder with the image

Edit the message with the image file and without generation. The loader is replaced by the image:

curl -X POST https://yoai.yophone.com/api/pub/editMessage \
-H "X-YoAI-API-Key: your YoAI api token" \
-F "to=123456789" \
-F "messageId=6f1d2c3e-8f00-11ef-8000-000000000001" \
-F "text=Here is your image" \
-F "file=@/path/to/result.png"

text can be empty or left out if the image needs no caption.

2b. Or mark the generation as failed

curl -X POST https://yoai.yophone.com/api/pub/editMessage \
-H "Content-Type: application/json" \
-H "X-YoAI-API-Key: your YoAI api token" \
-d '{
  "to": "123456789",
  "messageId": "6f1d2c3e-8f00-11ef-8000-000000000001",
  "text": "Sorry, I could not generate this image.",
  "generation": { "kind": "image", "status": "failed" }
}'

Errors

code	text	Reason
400	generation must be valid JSON	The generation form field is not valid JSON.
422	Error validating send message data / Error validating edit message data	kind or status is missing or has an unsupported value, or aspectRatio is not greater than 0. The errors field lists the parameters.

All errors are returned with HTTP status 200; the code field holds the actual error code.