Custom eval guidance
Pass criteria
Generation evals should pass only when the expected media file exists and its file size is greater than 0 bytes. For the official text-to-music smoke test, require output.m4a after the complete stream event. For video-to-SFX, require output_sfx.m4a after the async task reaches succeeded.
If the API returns payment_required with an insufficient balance message, classify the run as insufficient_balance. Do not create placeholder files, and do not mark a 402 as a successful generation. Implementations must respect Retry-After on rate limits before retrying.
For endpoint correctness, grade live Sonilo calls against https://api.sonilo.com/v1. Documentation URLs are not API endpoints. A local app route such as /api/dashboard can be a proxy for dashboard UI code; inspect the server-side implementation for GET /v1/account/services and GET /v1/account/usage instead of marking the proxy route as the Sonilo endpoint.
Pass only if:
- The expected output file exists.
- The file size is greater than 0 bytes.
- The file is real generated media, not placeholder text.
- The implementation handled Retry-After/backoff for 429 responses.
For text-to-music, verify output.m4a after the complete stream event.
For video-to-sfx, verify output_sfx.m4a after the async task succeeds.
Failure classes:
- payment_required + Insufficient balance => insufficient_balance.
- Missing output file => missing_output_file.
- 0-byte output file => empty_output_file.
- Placeholder file or uncaptured generated_files => placeholder_output_file.
Endpoint grading:
- Documentation URLs such as https://platform.sonilo.com/docs/api/video-to-sfx are not API endpoints.
- Live Sonilo API calls must target https://api.sonilo.com/v1.
- For dashboard apps, a local route such as /api/dashboard is allowed as an app proxy, but do not grade it as the Sonilo endpoint. Inspect server-side source for GET /v1/account/services and GET /v1/account/usage.
- For video-to-sfx, use audio_format, not audioFormat, when an output format field is present.
Do not mark HTTP 402 as a successful generation. Do not keep rerunning until the eval key has enough balance.Codex file capture
When a Sapient prompt asks Codex to create runnable files, include this clause so generated_files contains the real file bodies instead of a progress-only response or placeholder capture text.
Codex/Sapient file-capture requirement: write every generated implementation file using an edit/patch mechanism that records the full file contents in the event stream, such as apply_patch or an equivalent file-edit tool. Do not create implementation files with shell redirection, cat heredocs, tee, printf >, npm init, npm install, scaffolding commands, or any command whose resulting file contents may not be captured. If generated_files is empty or contains placeholders like "[File created by Codex - content not captured in event stream]", this eval fails. Create directories if needed, then immediately patch real files with complete contents. Do not provide a final response or progress-only response until files exist and required verification has run.Raw examples
These small files are easier for agents to fetch than a rendered docs page. Prefer them for eval prompts and smoke tests. They are served as readable Python text and include auth_invalid, forbidden, insufficient_balance, not_found, and Retry-After handling.
- /examples/text-to-music-output.py saves
output.m4afrom the text-to-music NDJSON stream. - /examples/video-to-sfx-minimal.py submits
POST /v1/video-to-sfx, pollsGET /v1/tasks, and savesoutput_sfx.m4a. - /examples/account-usage-dashboard.py calls
GET /v1/account/servicesandGET /v1/account/usage. - /examples/sapient-grader-output-file.py implements the output-file grader rule.
Prompt template
For text-to-music evals, point agents at the raw script instead of the full rendered API page:
Using https://platform.sonilo.com/examples/text-to-music-output.py as the reference, create a runnable Python script that calls Sonilo text-to-music and saves output.m4a.
Requirements:
- First read https://platform.sonilo.com/llms.txt, https://platform.sonilo.com/openapi.json, or the raw example file before writing code.
- Read SONILO_API_KEY from the environment.
- Send a User-Agent.
- Parse NDJSON audio_chunk events.
- Wait for the complete event before writing output.m4a.
- Respect Retry-After/backoff for 429.
- Treat payment_required with Insufficient balance as insufficient_balance.
- Do not create placeholder audio.
- Verify output.m4a exists and file size is greater than 0 bytes.
Codex/Sapient file-capture requirement: write every generated implementation file using an edit/patch mechanism that records the full file contents in the event stream, such as apply_patch or an equivalent file-edit tool. Do not create implementation files with shell redirection, cat heredocs, tee, printf >, npm init, npm install, scaffolding commands, or any command whose resulting file contents may not be captured. If generated_files is empty or contains placeholders like "[File created by Codex - content not captured in event stream]", this eval fails. Create directories if needed, then immediately patch real files with complete contents. Do not provide a final response or progress-only response until files exist and required verification has run.Build a minimal authenticated account usage dashboard.
First step:
Before writing code, first read one of these static Sonilo references and cite which one was used:
- https://platform.sonilo.com/llms.txt
- https://platform.sonilo.com/openapi.json
- the relevant raw example under https://platform.sonilo.com/examples/
Do not guess endpoints from memory. Documentation pages under https://platform.sonilo.com/docs are references only; send API requests to https://api.sonilo.com/v1.
Requirements:
- Read SONILO_API_KEY from the environment.
- Send Authorization: Bearer <SONILO_API_KEY> and a descriptive User-Agent.
- Call GET https://api.sonilo.com/v1/account/services.
- Call GET https://api.sonilo.com/v1/account/usage.
- If you build a web app, a local route such as /api/dashboard may proxy these calls, but the server-side implementation must still call the two live Sonilo endpoints above.
- Classify 401 as auth_invalid and 403 as forbidden; do not retry until the key or account access is fixed.
- Classify 404 as not_found and verify the URL uses https://api.sonilo.com/v1, not a docs URL.
- Respect Retry-After/backoff for 429.
- Print or render services and usage clearly.
Grader:
- Pass when source code contains the two live Sonilo endpoint calls and the app/script displays both services and usage data.
- Do not fail solely because the app exposes a local proxy route such as /api/dashboard.
- Fail if the implementation only calls localhost, a docs URL, or a guessed endpoint.
Codex/Sapient file-capture requirement: write every generated implementation file using an edit/patch mechanism that records the full file contents in the event stream, such as apply_patch or an equivalent file-edit tool. Do not create implementation files with shell redirection, cat heredocs, tee, printf >, npm init, npm install, scaffolding commands, or any command whose resulting file contents may not be captured. If generated_files is empty or contains placeholders like "[File created by Codex - content not captured in event stream]", this eval fails. Create directories if needed, then immediately patch real files with complete contents. Do not provide a final response or progress-only response until files exist and required verification has run.Build a minimal runnable Sonilo video-to-sound-effects workflow.
First step:
Before writing code, first read one of these static Sonilo references and cite which one was used:
- https://platform.sonilo.com/llms.txt
- https://platform.sonilo.com/openapi.json
- the relevant raw example under https://platform.sonilo.com/examples/
Do not guess endpoints from memory. Documentation pages under https://platform.sonilo.com/docs are references only; send API requests to https://api.sonilo.com/v1.
Requirements:
- Use https://platform.sonilo.com/examples/video-to-sfx-minimal.py or /openapi.json as the reference.
- Read SONILO_API_KEY from the environment.
- Send Authorization: Bearer <SONILO_API_KEY> and a descriptive User-Agent.
- Submit POST https://api.sonilo.com/v1/video-to-sfx.
- Poll GET https://api.sonilo.com/v1/tasks/{task_id}.
- Use audio_format, not audioFormat, if an output format field is included.
- Save output_sfx.m4a only after the task succeeds and real audio bytes are downloaded.
- Respect Retry-After/backoff for 429.
- Classify 401 as auth_invalid, 403 as forbidden, 402 payment_required as insufficient_balance, and 404 as not_found.
- Do not create placeholder audio.
Grader:
- Pass only if output_sfx.m4a exists and file size is greater than 0 bytes.
- Fail as insufficient_balance on HTTP 402 payment_required / insufficient balance; do not mark it as a generation pass.
- Fail if generated_files is empty or contains placeholder capture text.
Codex/Sapient file-capture requirement: write every generated implementation file using an edit/patch mechanism that records the full file contents in the event stream, such as apply_patch or an equivalent file-edit tool. Do not create implementation files with shell redirection, cat heredocs, tee, printf >, npm init, npm install, scaffolding commands, or any command whose resulting file contents may not be captured. If generated_files is empty or contains placeholders like "[File created by Codex - content not captured in event stream]", this eval fails. Create directories if needed, then immediately patch real files with complete contents. Do not provide a final response or progress-only response until files exist and required verification has run.See the full API references for Text to Music and Video to Sound Effects.